.. _api-access:


API Access
==========

The Dimensions Analytics API is available through an institutional subscription, subject to restrictions on use. `Contact us <https://www.dimensions.ai/request-a-demo-or-quote/>`_ for more information on licensing for your institution. Digital Science offers free access to the Analytics API for eligible scientometric research projects; please `click here to learn more <https://www.dimensions.ai/scientometric-research/>`_.


.. _analytics-and-cris:

The Analytics API and the CRIS API
----------------------------------

The Dimensions Search Language is the query language behind two Dimensions
APIs. Both use the same grammar, the same data sources and the same two-step
authentication flow described on this page — but they are separate products,
served from separate endpoints, and each is intended for a different type of
use.

Analytics API
  The main Dimensions API, and the primary subject of this documentation.
  It supports the **full DSL feature set**, including faceting and
  aggregations, :ref:`expert identification <expert-identification>` and all
  :ref:`functions <functions>`. It is designed for complex, interactive
  analytical tasks — scientometric analyses, reporting, one-off data
  investigations — and is **not** intended to power applications, dashboards
  or other derivative products (see :ref:`Reasonable use <usage-notes>`).

CRIS API
  A simplified version of the Analytics API for **integrating Dimensions
  metadata into research information management software** — CRIS systems,
  institutional repositories, faculty activity systems and similar. It is
  served from a dedicated endpoint (e.g. ``https://cris-api.dimensions.ai``)
  and is versioned independently of the Analytics API, with a slower release
  cadence so that integrations remain stable. Compared to the Analytics API
  it does **not** support faceting or the expert identification workflow.

.. note::
  If you have questions about your organizational subscriptions to Dimensions,
  or if you're a current subscriber and need help using the APIs,
  `please contact us <https://www.dimensions.ai/get-in-touch/>`_.


.. _api-key:

Getting an API Key
------------------

Once you have API access, you'll be able to generate a new API Key by going to the 'My Account' section of the Dimensions web application. 

.. image:: _static/images/api-key-dimensions.jpg
  :width: 70%
  :align: center
  :alt: Getting an API key 


Querying the API
----------------


Querying the Dimensions API always involves **two steps**: 

1. Sending your credentials (key) to the authentication url, in order to retrieve a query **token**.
2. Sending the token and a DSL query to the query url, in order to retrieve **JSON data**. 


.. important::
  The Analytics API and the CRIS API are limited to 30 requests per IP
  address per minute. The query token is valid for around 2 hours, so it
  should be re-obtained when it expires.


The diagram below provides an overview of these operations.  

.. image:: _static/images/api-endpoints.png
  :width: 70%
  :align: center
  :alt: API endpoints 



.. _endpoints:

API Endpoints
+++++++++++++

The API includes two groups of endpoints: a) for authentication and b) for querying. 

The authentication endpoint is the same for all versions of the API. The querying endpoints instead are for specific versions of the API. 

.. list-table:: Authentication Endpoint
   :header-rows: 1

   * - Name
     - Endpoint Path
     - Description
   * - API Authentication
     - ``/api/auth``
     - The single authentication endpoint for all API versions. Returns a query token.


.. list-table:: Querying Endpoints
   :header-rows: 1

   * - Name
     - Endpoint Path
     - Description
   * - V1 (legacy)
     - ``/api/dsl/v1``
     - V1 API. Currenlty in maintenance mode. Removed in March 2022. 
   * - V2 (latest)
     - ``/api/dsl/v2``
     - V2 API. **Current** major version of the DSL.
   * - Current (alias)
     - ``/api/dsl``
     - Alias for current version of API. Will point to V1 till Dec 2021, then will point to V2.
   * - Current (alias, alternative path)
     - ``/api/dsl.json``
     - Alias for current version of API. Will point to V1 till Dec 2021, then will point to V2.

.. important::
  Add your Dimensions URL to the endpoint path in order to obtain the final API URL. Eg if your Dimensions URL is ``https://app.dimensions.ai``, your final authentication URL will be ``https://app.dimensions.ai/api/auth``. 



Python : raw access
-------------------

The following code snippet shows how to connect to the Dimensions API only using Python's `requests` library.

.. code-block:: python

  import requests

  #   The credentials to be used
  login = {
      'key': "your API key"
  }

  #   Send credentials to login url to retrieve token. Raise
  #   an error, if the return code indicates a problem.
  #   Please use the URL of the system you'd like to access the API
  #   in the example below.
  resp = requests.post('https://<your-url.dimensions.ai>/api/auth', json=login)
  resp.raise_for_status()

  #   Create http header using the generated token.
  headers = {
      'Authorization': "JWT " + resp.json()['token']
  }

  #   Execute DSL query.
  resp = requests.post(
      'https://<your-url.dimensions.ai>/api/dsl/v2',
      data='search publications return publications'.encode(),
      headers=headers)

  #   Display raw result
  print(resp.json())


The snippet above uses the **key** authentication method, which is the primary method for most API servers (see also :ref:`Getting an API Key <api-key>` for more information on how to obtain a key). 


.. _escaping-rules:

.. note::
  Please note escaping rules in `Python <http://python-reference.readthedocs.io/en/latest/docs/str/escapes.html>`_.
  For example, when writing a query with escaped quotes, such as:

  .. code-block:: none

      search publications for "\"phrase 1\" AND \"phrase 2\""

  in Python, it is necessary to escape the backslashes as well, so it would look like:

  .. code-block:: none

    resp = requests.post(
        'https://<your-url.dimensions.ai>/api/dsl/v2',
        data='search publications for "\\"phrase 1\\" AND \\"phrase 2\\""',
        headers=headers)

  Similar escaping rules might apply to other programming languages than Python as well.
  **Alternatively**, :ref:`triple-quotes-syntax` can be used to avoid having to escape quote characters.


.. _python-dimcli:

Python : Dimcli
----------------
Dimensions APIs can be accessed also using `Dimcli <https://digital-science.github.io/dimcli/getting-started.html>`_, an open-source Python client. Dimcli is a convenient way to
connect to, query and analyze the results of Dimensions API.


.. code-block:: python

  import dimcli

  dimcli.login(key="123456789qwertyuiop",  
                 endpoint="https://app.dimensions.ai/api/dsl/v2")

  dsl = dimcli.Dsl()

  data = dsl.query("""search grants for "malaria" return researchers""")

  print(data.json)
  # {'researchers': [{'id': 'ur.01332073522.49',
  #   'count': 75,
  #   'last_name': 'White',
  #   'first_name': 'Nicholas J'},
  #   {'id': 'ur.01343654360.43',
  #   'count': 59,
  #   'last_name': 'Marsh',
  #   'first_name': 'Kevin'},
  #   .............
  #   ],
  # '_stats': {'total_count': 8735}}
  

The API Lab includes several notebooks demonstrating the practical use of Dimcli. In particular, these two are a good place to start:

* `The Dimcli Python library: Installation and Querying <https://api-lab.dimensions.ai/cookbooks/1-getting-started/1-Using-the-Dimcli-library-to-query-the-API.html>`_
* `The Dimcli Python library: Working with Pandas Dataframes <https://api-lab.dimensions.ai/cookbooks/1-getting-started/3-Working-with-dataframes.html>`_


.. note::

  Dimcli includes also a command line interface (CLI) that makes it easier to learn the grammar of the Dimensions Search Language. Calling ``dimcli`` from a Terminal opens an interactive query console with syntax autocompletion, persistent history across sessions, pretty-printing and preview of JSON results, export to HTML and CSV, and more.

  .. image:: _static/images/dimcli_animated.gif
      :width: 70%
      :align: center
      :alt: Dimcli CLI



`curl` + `jq`
-------------

This example shows a minimal way to query the API. This should be easily transferable to any other programming language or environment.

.. code-block:: shell

  export DSL_TOKEN=$(curl https://<your-url.dimensions.ai>/api/auth.json -d '{"key": "your API key"}' -s|jq -r .token)

  curl https://<your-url.dimensions.ai>/api/dsl/v2 -H "Authorization: JWT $DSL_TOKEN" -d 'search publications return publications' -s|jq


.. note::
  Note that `jq` tool is used to extract a `"token"` value from the JSON response in the first request.
  In the second request, `jq` is used only to pretty print the result so it's use is optional.


PowerShell
----------

This is an equivalent example of the above CURL + JQ Example, but usable in the PowerShell enivornment.

.. code-block:: shell

  $DSL_TOKEN = (Invoke-RestMethod -Uri https://<your-url.dimensions.ai>/api/auth.json -Method Post -Body (@{'key' = 'your API key'} | ConvertTo-JSON)).token

  Invoke-RestMethod -Uri https://<your-url.dimensions.ai>/api/dsl/v2 -Method Post -H @{Authorization = "JWT $DSL_TOKEN"} -Body 'search publications return publications'




Postman
-------

This examples shows how to set up `Postman <https://www.getpostman.com>`_ to query the Dimensions API. This can be achieved in two simple steps.  

**1. Obtaining a JWT token**  

Make a POST request to ``https://app.dimensions.ai/api/auth.json`` with body ``{ "key": "<your-API-key>"}``

This will return a JWT token, which should be noted as it will be used in the next step. 

.. image:: _static/images/postman_1.png
    :width: 80%
    :align: center
    :alt: postman example - part 1


**2. Using the token to query the API**

Make a new POST request by adding the token to the `Headers` panel in this format: `Authorization : JWT {theToken}`. 

.. image:: _static/images/postman_2.png
    :width: 80%
    :align: center
    :alt: postman example - part 2

Finally, Compose your query in the request `body` section:

.. image:: _static/images/postman_3.png
    :width: 80%
    :align: center
    :alt: postman example - part 3


.. note::
  Another approach to get started with Postman is by using the `cURL importer <https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-data/>`_.



Dimensions Analytics MCP
------------------------

The :ref:`Dimensions Analytics MCP <mcp>` server connects AI assistants to the Dimensions API through the Model Context Protocol. Once configured, your assistant can search publications, grants, and researchers; run analytics; and explore the live schema — all via natural language. See the :ref:`MCP documentation <mcp>` for installation and usage.


Third-party Libraries and Tools
-------------------------------

dimensionsR Library
    The `dimensionsR library <https://github.com/massimoaria/dimensionsR>`_ is an open-source R-package to gather bibliographic data using the Dimensions API and the DSL. 

rdimensions Library
    Another client library `rdimensions <https://github.com/nicholasmfraser/rdimensions>`_ for interacting with the Dimensions API from the R environment.

Sidewall Python Library
    The `Sidewall library <https://github.com/caltechlibrary/sidewall>`_ is a Python package providing object classes for Dimensions entities, fetches data incrementally, caches results, copes with rate limits, and more, to make working with Dimensions in Python more natural. 

Biblioshiny
    Bibliometrix facilitates bibliometric analysis, using several APIs including the Dimensions Analytics API. Biblioshiny is a `Shiny <https://shiny.posit.co/>`_ app, providing a web-interface for bibliometrix.