The Dimensions Search Language

Version 2.0.0

Welcome to the documentation of the Dimensions Search Language (DSL) project. The DSL enables users to perform analytics on the Dimensions database.

This documentation contains high-level information about the project and its development, as well as the language’s features and usage. Please see the APIs Homepage for more details about available API packages and subscriptions.


This is the latest version of the API, released in October 2021.

Users who are still using previous versions of the API are encouraged to migrate to this version as soon as possible. The previous version, API Version 1, is in maintenance mode and due to be removed in March 2022.

See the how to upgrade from V1 to V2 page for more information on backward-incompatible changes.


  • Oct 2021: API V2 is released. V1 enters maintenance mode.

  • Dec 2021: V2 is used by default on Gsheets plugin and Dimcli.

  • Jan 2022: V2 is used by default on /api/dsl endpoint.

  • Mar 2022: API V1 is retired.


The Dimensions Analytics API is subscription-only, so your Dimensions account needs to be activated for this service and subject to restrictions on use. Please send an email to if you have any questions.


Explore real-world applications of the API at the Dimensions API Lab , an open-source repository of Jupyter notebooks demonstrating how to carry out common scholarly analytics tasks e.g. building a citation network, doing a journal competitors analysis, tracking researchers’ affiliations over time etc..