The Pure API allows you to get information about metrics and fetch metric values associated with individual content items. An endpoint only has metrics related operations when the content type handled by the endpoint supports metrics, such as the /research-outputs endpoint.

Metric collections are used as containers for metric values associated with a content item. To work with data in a metric collection, you first need to determine the id of the metric collection you want to access. You can then request a metric collection for each content item you want metric values from.

Determining what metric collection to access

You can use the /allowed-metric-collections operation to get information about metric collections available for content managed by the current endpoint in the form of MetricCollectionDefinition objects. A metric collection definition contains information about a set of related metrics. A metric collection definition is identified by a globally unique id and it contains a number of MetricDefinition objects, each describing the structure of a specific metric. A metric definition can be identified by an id that is unique across its owning metric collection definition. A metric definition's valueType informs about the type of value supported. A metric definition that has 'integer' as its valueType is referred to as an "integer-based metric".

Types available are:

• Boolean
• Classification
• Decimal
• Integer
• String

https://{your Pure hostname}/ws/api/research-outputs/allowed-metric-collections

{
  "items": [
    {
      "metrics": [
        {
          "metricId": "downloads",
          "valueType": "INTEGER",
          "name": {
            "en_GB": "Downloads",
          }
        }
      ],
      "collectionId": "downloadStatistics",
      "name": {
        "en_GB": "Download statistics",
      },
      "sourceClassificationScheme": {
        "systemName": "ClassificationScheme",
        "uuid": "69525778-3059-4012-9254-708c337cf801"
      }
    },
    ...
  ]
}

You currently only have access to a subset of Pure's metrics using the Pure API and the /allowed-metric-collections operation lets you see which ones.

Fetching a metric collection

You work with metric data of a content item using MetricCollection objects. A metric collection is a container for metric values associated with a content item, with a structure defined by a metric collection definition. You can think of a metric collection as an instance of a metric collection definition, specific to a content item.

You can access metric data of a metric collection from a specific content item using the /metrics/{collection-id} sub-resource of the content item. The collection-id argument specifies the id of the metric collection you want metric values for.

https://{your Pure hostname}/ws/api/research-outputs/fd50c80b-6693-486f-82ce-35f164fd6fcc/metrics/downloadStatistics

{
  "collectionId": "downloadStatistics",
  "items": [
    {
      "source": {
        "uri": "/dk/atira/pure/source/citation/downloadstatistics",
        ...
      },
      "year": 2021,
      "metricValues": [
        {
          "metricId": "downloads",
          "integerValue": 42
        }
      ]
    },
    {
      "source": {
        "uri": "/dk/atira/pure/source/citation/downloadstatistics",
         ...
       },
      "year": 2022,
      "metricValues": [
        {
          "metricId": "downloads",
          "integerValue": 12
        }
      ]
    }
  ]
}

A set of metric values for each of the metrics supported by the collection can be uniquely identified by a combination of its source, category, and year; multiple values for the same metric are possible as long as each value is for a distinct combination. As you see in the "metric collection where metric values are identified by 'source' and 'year'" sample request, where metric values are not identified by a category, a metric collection may not specify one or more of the source, category, and year fields.

You will get an empty metric collection when a content item does not have metric values for a requested metric collection id.

https://{your Pure hostname}/ws/api/research-outputs/fd50c80b-6693-486f-82ce-35f164fd6fcc/metrics/plumXMentions

{
  "collectionId": "plumXMentions",
  "items": []
}