Calling the API > Response formats

http://api.ids.ac.uk/openapi/ site / search / data object / parameter / response format ?query

The response format is specified to determine the data returned: Values allowed:

  • Short (default)
  • Full

By default, the Short format is returned. Note that you can extend the short format using the extra_fields query parameter

Short Format

The short format has four fields per item returned:

Field Name Description
name Name of organisation
object_id Unique idenitfier of this organisation
object_type The type of asset, in this case “Organisation”
metadata_url Web-accessible uri for this object

At the top level, the response has two entries – metadata and results.

The metadata section can contain:

  • num_results – the total number of results for that search.
  • start_offset – the offset into the results of the items in the results section.
  • next_page – a link to the next page of results (only present if there are more results after this page).
  • prev_page – a link to the previous page of results (only present if there are more results before this page).

The results section is a list of results. Each item has data as specified by the format part of the URL, as for the single object response.

A sample of the data returned for a search for documents in Eldis that mention “Zimbabwe” (e.g. http://api.ids.ac.uk/openapi/eldis/search/documents/?q=zimbabwe) in short format would be:

{
    "metadata": {
        "next_page": "http://api.ids.ac.uk/openapi/eldis/search/documents/?q=zimbabwe&num_results=10&start_offset=10",
        "start_offset": 0,
        "total_results": 163
    },
    "results": [
        {
            "metadata_url": "http://test.api.ids.ac.uk/openapi/eldis/get/documents/A26871/full/zimbabwe-financial-information-centre/",
            "object_id": "A26871",
            "object_type": "Document",
            "title": "Zimbabwe Financial Information Centre"
        },
        {
            "metadata_url": "http://test.api.ids.ac.uk/openapi/eldis/get/documents/A8541/full/brain-strain-the-burden-of-persistent-depression-in-zimbabwe/",
            "object_id": "A8541",
            "object_type": "Document",
            "title": "Brain strain: the burden of persistent depression in Zimbabwe"
        },
        {
            "metadata_url": "http://test.api.ids.ac.uk/openapi/eldis/get/documents/A8446/full/mental-arithmetic-the-economics-of-mental-illness-in-zimbabwe/",
            "object_id": "A8446",
            "object_type": "Document",
            "title": "Mental arithmetic: the economics of mental illness in Zimbabwe"
        },
    ]
}

Extra Fields

You can request extra fields by using the extra_fields query parameter. This can help restrict the size of the call response, as you do not have to return all fields.

The available fields vary by object type. The complete list of fields can be seen by using the fieldlist query. Note that not every object has every field – in fact no object has every field, as some fields are specific to one object type or another.

For multiple fields, put a + in between them. So in order to get the short format, but add the headline and array of theme information, you would add

extra_fields=headline+category_theme_array

These fields only exist for documents, so we could do:

http://api.ids.ac.uk/openapi/eldis/get/documents/A12345/short?extra_fields=headline+category_theme_array

Full format

The full format has every field available for each item returned.

At the top level, the response has two entries – metadata and results.

The metadata section can contain:

  • num_results – the total number of results for that search.
  • start_offset – the offset into the results of the items in the results section.
  • next_page – a link to the next page of results (only present if there are more results after this page).
  • prev_page – a link to the previous page of results (only present if there are more results before this page).

The results section is a list of results. Each item has data as specified by the format part of the URL, as for the single object response.

A sample of the data returned for a search for documents in Eldis that mention “Zimbabwe” (e.g. http://api.ids.ac.uk/openapi/eldis/search/documents/full?q=zimbabwe) in short format would be:

{
    "metadata": {
        "next_page": "http://api.ids.ac.uk/openapi/eldis/search/documents/full?q=zimbabwe&num_results=10&start_offset=20",
        "prev_page": "http://api.ids.ac.uk/openapi/eldis/search/documents/full?q=zimbabwe&num_results=10&start_offset=0",
        "start_offset": 10,
        "total_results": 689
    },
    "results": [
        {
            "author": [
                ""
            ],
            "category_region_array": {
                "Region": [
                    {
                        "deleted": "0",
                        "metadata_url": "http://api.ids.ac.uk/openapi/eldis/get/regions/C21/full/africa/",
                        "object_id": "C21",
                        "object_name": "Africa",
                        "object_type": "region"
                    }
                ]
            },
            "category_region_path": [
                "Africa"
            ],
            "category_theme_path": [
                ""
            ],
            "country_array": {
                "Country": [
                    {
                        "alternative_name": "Zimbabwe",
                        "iso_two_letter_code": "ZW",
                        "metadata_url": "http://api.ids.ac.uk/openapi/eldis/get/countries/A1243/full/zimbabwe/",
                        "object_id": "A1243",
                        "object_name": "Zimbabwe",
                        "object_type": "Country"
                    }
                ]
            },
            "country_focus": [
                "Zimbabwe"
            ],
            "date_created": "2001-08-12 23:00:00",
            "date_updated": "2007-03-29 22:22:39",
            "description": "WWW site has information on stock exchange news and trends and market reports",
            "et_al": "false",
            "keyword": [
                "Finance",
                "Stock markets",
                "Stocks"
            ],
            "language_name": "English",
            "legacy_id": "DOC5776",
            "metadata_url": "http://api.ids.ac.uk/openapi/eldis/get/documents/A26871/full/zimbabwe-financial-information-centre/",
            "name": "Zimbabwe Financial Information Centre",
            "object_id": "A26871",
            "object_type": "Document",
            "publication_date": "1999-01-01 00:00:00",
            "publisher": "Africa Online",
            "publisher_array": {
                "Publisher": [
                    {
                        "metadata_url": "http://api.ids.ac.uk/openapi/eldis/get/organisations/A2363/full/africa-online/",
                        "object_id": "A2363",
                        "object_name": "Africa Online",
                        "object_type": "Organisation"
                    }
                ]
            },
            "publisher_country": "",
            "site": "eldis",
            "timestamp": "2012-02-13 17:05:39",
            "title": "Zimbabwe Financial Information Centre",
            "urls": [
                "http://www.zic.com.au/linkshi.htm"
            ],
            "website_url": "http://www.eldis.org/go/display&type=Document&id=26871"
        }, 

    ]
}

Field List Response Format

This is just a list of the names of the fields present. A full list of available fields will be available soon.

Category Count Response Format

This will have a metadata section, giving the total number of results for the query, and a xxx_count section which will be a list of lists – each list will have two items. The first item will be the name of the category and the second item will be the number of times the category appears in the results.

Rate limiting

In order to balance server loads, we allow users to make a limited number of calls to the Knowledge Services API in a given hour and return a subset of the full field list. The API does account-based rate limiting (per API Key).

Usage tiers are as follows:

User Maximum call rate Maximum number of items per call
General User 150 calls/hour 2000
Offline Application User 300 calls/hour 2000
Partner 300 calls/hour 2000

If you want to get a higher level of access, please contact us – api@ids.ac.uk

Error handling

  • 400 – The URL was in an invalid format. There will be a message explaining why.
  • 404 – No object (of type specified) found with that object_id.
  • 500 – There was a server fault. Try again later.

Formatting available

The data can be returned as JSON or as XML, with JSON as the default.

To specify XML as the response format, pass

format=xml

in the query string. e.g.

http://api.ids.ac.uk/openapi/eldis/search/documents/full?region=C30&format=xml


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.