Skip to content

Departments

The Departments endpoint lists the institutional departments configured for your instance, so you can retrieve the department_id values used by the filter[department_id] filter without clicking through each department in the Altmetric Explorer.

Each department's id is the exact value to pass to filter[department_id] on the other endpoints (for example Research Outputs).

Note

This endpoint is only available to organizations with an institutional data implementation (PURE, Elements, OAI-PMH, or CSV). Instances without an integration receive an empty data array.

Results are paginated and, by default, the size is set to 25 items per page. You can change this so that a maximum of 100 items are returned per request.

Request

GET /explorer/api/departments

GET /explorer/api/departments?digest={digest}&key={key}

Basic GET request to list your institution's departments, ordered by name.

Example request:

GET /explorer/api/departments?key=YOUR_API_KEY&digest=YOUR_DIGEST HTTP/1.1
Host: www.altmetric.com

Query parameters:

Parameter Required Accepts Description
digest Yes A valid digest See Authentication
key Yes A valid key See Authentication

Note

This endpoint takes no filter parameters — it always returns every department for your institution. Sign the request as you would an unfiltered query (the digest of an empty filter set).

Response object

A GET request to the departments endpoint returns a JSON object with meta, links, and data.

Meta

Information about the request and the response.

Query

Key Type Description
key string The API key used to make the request.
digest string The digest included in the request.
page object Pagination details: number (the current page) and size (the page size; default 25, maximum 100).

Note

Unlike the other endpoints, this one accepts no filters, so meta.query never contains a filter key.

Response

Key Type Description
status string Response status for the request.
description string A human-readable description of the listing, for example All departments from University of Example.
total-results number The total number of departments for your institution.
total-pages number The number of pages required to consume all departments at the current page size.

Errors

An array of objects containing information relating to any errors preventing the response from being returned. See Status codes for additional information.

Key Type Description
status string HTTP response code relating to the request.
code string Altmetric status code for the error.
title string The Altmetric assigned title for the error.
detail string A detailed description of what the error is.
source object An object that contains information relating to the cause of the error. See Source for more information.

Source

An object that contains the parameter that resulted in the error.

Key Type Description
key string Currently the only key returned is parameter
value string Available values are key and digest

Status codes

These error codes are common to every Altmetric Explorer API endpoint. Some endpoints define additional error codes, which are documented on their respective pages.

Status Code Title Details
400 missing_api_key Missing API key Requests to the Altmetric Explorer API must include your API key in the "key" parameter. You did not supply a key.
400 invalid_api_key Invalid API key Requests to the Altmetric Explorer API must include your API key in the "key" parameter. The supplied key was not valid.
400 expired_api_key Expired API key Requests to the Altmetric Explorer API must include your API key in the "key" parameter. The supplied key was expired.
400 invalid_digest Invalid API request signature Requests to the Altmetric Explorer API must be signed with your API secret, and the digest provided in the "digest" parameter. The signature for this request was missing or invalid.
400 invalid_filter_format Invalid filter format The "filter" parameter must be a hash of filter criteria. The supplied filter was not in the correct format.
400 no_api_access API access not allowed Your organisation does not have access to the Altmetric Explorer API.

Errors example

{
  "meta": {
    "response": {
      "status": "error"
    }
  },
  "errors": [
    {
      "status": "400",
      "code": "invalid_digest",
      "title": "Invalid API request signature",
      "detail": "Requests to the Altmetric Explorer API must be signed with your API secret, and the digest provided in the \"digest\" parameter. The signature for this request was missing or invalid.",
      "source": {
        "parameter": "digest"
      }
    }
  ]
}

Object containing page navigation information.

Key Type Description
self string The self link is a URL that refers back to the exact resource representation that was requested.
first string The first link provides a URL to access the first page of results.
last string The last link provides a URL to access the last page of results.
next string The next link provides the URL to access the next page of data. It is not present on the last page of results.
prev string The prev link provides the URL to access the previous page of data. It is not present on the first page of results.

Data

An array of department objects.

Key Type Description
id string The department identifier. This is the exact value to pass to filter[department_id]. Its format is derived from your data integration and often includes an instance prefix (for example example-university:group:2ba9429d-a319-4018-bd02-02b55314c19d) — pass it verbatim.
type string department
attributes > name string The department name.

Response example

{
  "meta": {
    "query": {
      "key": "YOUR_API_KEY",
      "digest": "YOUR_DIGEST",
      "page": {
        "number": 1,
        "size": 25
      }
    },
    "response": {
      "status": "ok",
      "description": "All departments from University of Example",
      "total-results": 42,
      "total-pages": 2
    }
  },
  "links": {
    "self": "https://www.altmetric.com/explorer/api/departments?digest=YOUR_DIGEST&key=YOUR_API_KEY&page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "first": "https://www.altmetric.com/explorer/api/departments?digest=YOUR_DIGEST&key=YOUR_API_KEY&page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "last": "https://www.altmetric.com/explorer/api/departments?digest=YOUR_DIGEST&key=YOUR_API_KEY&page%5Bnumber%5D=2&page%5Bsize%5D=25",
    "next": "https://www.altmetric.com/explorer/api/departments?digest=YOUR_DIGEST&key=YOUR_API_KEY&page%5Bnumber%5D=2&page%5Bsize%5D=25"
  },
  "data": [
    {
      "id": "example-university:group:2ba9429d-a319-4018-bd02-02b55314c19d",
      "type": "department",
      "attributes": {
        "name": "Department of Biology"
      }
    },
    {
      "id": "example-university:group:9a2d7d0a-d1fe-4f04-9ea1-c6112c6eb83b",
      "type": "department",
      "attributes": {
        "name": "Department of Chemistry"
      }
    }
  ]
}