Calling the API > Count

http://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
http://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 http://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:

http://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": "http://api.ids.ac.uk/openapi/eldis/get/regions/C21/full/africa/",
            "object_id": "C21",
            "object_name": "Africa",
            "object_type": "region"
        },
        {
            "count": 3497,
            "metadata_url": "http://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": "http://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": "http://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": "http://api.ids.ac.uk/openapi/eldis/get/regions/C24/full/europe/",
            "object_id": "C24",
            "object_name": "Europe",
            "object_type": "region"
        },
        {
            "count": 1098,
            "metadata_url": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://api.ids.ac.uk/openapi/eldis/get/regions/C30/full/south-asia/",
            "object_id": "C30",
            "object_name": "South Asia"

Other examples:

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

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

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

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

Latest updates

Additional fields in count results
Changes to structure of count results


Leave a Reply

Your email address will not be published. Required fields are marked *

IDS Open API

The IDS Knowledge Services API button

Your feedback

Please let us know if any of our documentation is not clear, or you have an queries, using the comments box at the bottom of each page.