https://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. https://api.ids.ac.uk/openapi/eldis/search/documents/?q=zimbabwe) in short format would be:
{
"metadata": {
"next_page": "https://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:
https://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. https://api.ids.ac.uk/openapi/eldis/search/documents/full?q=zimbabwe) in short format would be:
{
"metadata": {
"next_page": "https://api.ids.ac.uk/openapi/eldis/search/documents/full?q=zimbabwe&num_results=10&start_offset=20",
"prev_page": "https://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": "https://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": "https://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": "https://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": "https://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.
https://api.ids.ac.uk/openapi/eldis/search/documents/full?region=C30&format=xml