Identifier Lists¶

The Identifier Lists endpoint creates (or finds, if one already exists) a reusable list of scholarly identifiers and returns its unique ID. The returned identifier_list_id can then be supplied via filter[identifier_list_id] to other endpoints.

The endpoint is idempotent. Submitting the same identifier content again returns the same id rather than creating a duplicate list.

Supported identifier types¶

Identifiers can be separated by whitespace (spaces, tabs, or newlines) and may be mixed in a single request. The following types are recognised:

The altmetric: prefix is required for Altmetric IDs to disambiguate them from PubMed IDs.

Request¶

POST /explorer/api/identifier_lists¶

POST /explorer/api/identifier_lists HTTP/1.1
Host: www.altmetric.com
Content-Type: application/x-www-form-urlencoded

key={key}&digest={digest}&identifiers={identifiers}

POST request to create (or find) an identifier list.

Example request:

POST /explorer/api/identifier_lists HTTP/1.1
Host: www.altmetric.com
Content-Type: application/x-www-form-urlencoded

key=YOUR_API_KEY&digest=YOUR_DIGEST&identifiers=10.1038%2Fnplants.2015.3%0Aaltmetric%3A12345

Body parameters:

Digest¶

Unlike the other Altmetric Explorer API endpoints, the digest for this endpoint is the HMAC-SHA1 of the raw identifiers body content (using your API secret as the key, with hyphens stripped). The alphabetical-filter convention described in Signing your own requests does not apply here, because this endpoint has no filters.

api_secret = 'YOUR_API_SECRET'
identifiers = "10.1038/nplants.2015.3\naltmetric:12345"
digest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('SHA1'), api_secret.delete('-'), identifiers)
#=> "YOUR_DIGEST_RESULT"

The same byte-for-byte string passed as identifiers in the body must be used to compute the digest — including any whitespace.

Response object¶

A successful POST request to the identifier_lists endpoint returns a JSON object with the following keys.

Errors¶

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

Source¶

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

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.

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"
      }
    }
  ]
}

Additional error codes¶

In addition to the common error codes, the identifier lists endpoint can return:

Data¶

A single object describing the created (or found) identifier list.

Counts¶

The counts object only includes keys for identifier types that were recognised in the submitted content. Possible keys:

Unrecognised tokens are silently dropped from the counts but are preserved in content.

Data example¶

{
  "id": "5aca0b58-1e10-423f-80e9-6499ce59cebb",
  "counts": {
    "dois": 2,
    "altmetric_ids": 1
  },
  "content": "10.3133/pp1348 altmetric:101427008 10.1007/bf01734359"
}

Example response¶

{
  "meta": {
    "response": {
      "status": "ok"
    }
  },
  "data": {
    "id": "5aca0b58-1e10-423f-80e9-6499ce59cebb",
    "counts": {
      "dois": 2,
      "altmetric_ids": 1
    },
    "content": "10.3133/pp1348 altmetric:101427008 10.1007/bf01734359"
  }
}

Using the list¶

Once you have an id from the response, pass it as the identifier_list_id filter on any of the other Explorer API endpoints to query against the cohort:

GET /explorer/api/research_outputs?key=YOUR_API_KEY&digest=YOUR_DIGEST&filter[identifier_list_id]=5aca0b58-1e10-423f-80e9-6499ce59cebb HTTP/1.1
Host: www.altmetric.com

The digest for that GET is computed using the normal alphabetical-filter convention — see Signing your own requests. In this case the signing string would be identifier_list_id|5aca0b58-1e10-423f-80e9-6499ce59cebb.