Counting

https://api.ids.ac.uk/openapi/ site / count / data object / categories / query

A count is a dynamic clustering of objects or search results into categories  (theme, country, region, keywords). A count shows the number of hits within the search that match that category.

Counts are possible with any combination of the following objects and parameters:

Objects	Parameter
Documents	Theme
Organisations	Country
Items	Region
	Keyword

It’s easiest to understand what a count is is through an example

Count queries

You are able to combine the count and search functions to get a count of results for a specific search term.

So for

https://api.ids.ac.uk/openapi/eldis/count/documents/country/?q=undp

you would get a set of results that told you, for each country, how many documents existed that had the text “undp” and were concerned with that country.

Please note

It is NOT possible to query within the parameter type. e.g. A query for https://api.ids.ac.uk/openapi/eldis/count/documents/theme/?theme=C308

is not possible.

Count Results

All counts return the following fields:

count	Count of the matching parameter
object_id	Unique identifier for the object returned. This may be used to construct look ups for additional data
object_name	The title of the document, name of an organisation etc.
object_type	The type of the object. This should match the type from the count
metadata_url	Link to the full details of the object

Additional fields

To reduce the number of lookups required in some circumstances, additonal information is provided with the results.

Countries

• iso_two_letter_code: ISO code field.

Themes

• level: The level of the category in the hierarchy

Examples

If you want to see how many documents are in each region in the Eldis data, you could use:

https://api.ids.ac.uk/openapi/eldis/count/documents/region

This would return:

{
    "metadata": {
        "total_results": 33757
    },
    "region_count": [
        {
            "count": 17037,
            "metadata_url": "",
            "object_id": "",
            "object_name": "",
            "object_type": ""
        },
        {
            "count": 7951,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C21/full/africa/",
            "object_id": "C21",
            "object_name": "Africa",
            "object_type": "region"
        },
        {
            "count": 3497,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C30/full/south-asia/",
            "object_id": "C30",
            "object_name": "South Asia",
            "object_type": "region"
        },
        {
            "count": 2976,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C22/full/east-asia-and-pacific/",
            "object_id": "C22",
            "object_name": "East Asia and Pacific",
            "object_type": "region"
        },
        {
            "count": 2900,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C26/full/latin-america-and-caribbean/",
            "object_id": "C26",
            "object_name": "Latin America and Caribbean",
            "object_type": "region"
        },
        {
            "count": 1992,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C24/full/europe/",
            "object_id": "C24",
            "object_name": "Europe",
            "object_type": "region"
        },
        {
            "count": 1098,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C27/full/middle-east-and-north-africa/",
            "object_id": "C27",
            "object_name": "Middle East and North Africa",
            "object_type": "region"
        },
        {
            "count": 598,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C29/full/russia-and-the-commonwealth-of-independent-states/",
            "object_id": "C29",
            "object_name": "Russia and the Commonwealth of Independent States",
            "object_type": "region"
        },
        {
            "count": 465,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C28/full/north-america/",
            "object_id": "C28",
            "object_name": "North America",
            "object_type": "region"
        },
        {
            "count": 430,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C23/full/eastern-europe/",
            "object_id": "C23",
            "object_name": "Eastern Europe",
            "object_type": "region"
        },
        {
            "count": 74,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C25/full/japan/",
            "object_id": "C25",
            "object_name": "Japan",
            "object_type": "region"
        }
    ]
}

So the total results of Eldis documents are 33757

"metadata": {
        "total_results": 33757
    }

17037 documents are about no particular region

            "count": 17037,
            "metadata_url": "",
            "object_id": "",
            "object_name": ""

7951 documents are about Africa

            "count": 7951,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C21/full/africa/",
            "object_id": "C21",
            "object_name": "Africa"

3497 documents are about South Asia

            "count": 3497,
            "metadata_url": "https://api.ids.ac.uk/openapi/eldis/get/regions/C30/full/south-asia/",
            "object_id": "C30",
            "object_name": "South Asia"

Other examples:

https://api.ids.ac.uk/openapi/bridge/count/documents/theme

this returns a count of the number of documents in BRIDGE by theme.

https://api.ids.ac.uk/openapi/eldis/count/organisations/keyword

this returns a count of all the organisations in Eldis by keyword.