https://api.ids.ac.uk/openapi/ site / search / data object / parameter / query
Queries
- General query fields
- Wildcard searches
- Dates
- Special query fields
- Searching by theme
- Searching by country
- Document-only fields
- Organisation-only fields
- Category-only fields
- Combining query fields
Results
- Sort order of results
- Pagination and offsets
General query fields
| Query Parameters: | |
|---|---|
| q | The text to search for across all fields. Note the search is not case-sensitive, although some other queries are case-sensitive. Results are returned in relevance rank sort order |
| country | One of:
|
| keyword | The name of a keyword to search for. |
| region | One of:
|
| theme | One of:
|
| license_type | The type of license for this data. |
See below for more details and examples of these options. Note that each of the query parameters above can only be included once in the query. If you do so the API will return with a status of 400 and a message telling you which parameter was repeated. See below for how to combine query terms.
Examples: https://api.ids.ac.uk/openapi/eldis/search/assets/?q=undp https://api.ids.ac.uk/openapi/bridge/search/documents/?country=Angola https://api.ids.ac.uk/openapi/eldis/search/organisations/?country=india&theme=climate%20change
Wildcard searching
Note that you can use * in your query, but not as the first character.
So you can use: https://api.ids.ac.uk/openapi/eldis/search/documents/?keyword=af* https://api.ids.ac.uk/openapi/eldis/search/documents/?keyword=af*ca but not: https://api.ids.ac.uk/openapi/eldis/search/documents/?keyword=*ca
Dates
| Query Parameters: | |
|---|---|
| metadata_published_after | Date after which the metadata was published. |
| metadata_published_before | Date before which the metadata was published. |
| metadata_published_year | The metadata was published during the specified year. |
For the first two, the date should be specified as YYYY-MM-DD (year, month, day). For the last option, the value is just the 4 digit year.
https://api.ids.ac.uk/openapi/eldis/search/documents/?q=undp&metadata_published_after=2001-01-01 Returns search results of documents that contain the phrase "undp" that were published after 2001. https://api.ids.ac.uk/openapi/eldis/search/documents/?q=undp&metadata_published_before=2001-01-01 Returns search results of documents that contain the phrase "undp" that were published before 2001. https://api.ids.ac.uk/openapi/eldis/search/documents/?q=undp&metadata_published_year=2001 Returns search results of documents that contain the phrase "undp" that were published in the year 2001.
Special query fields
| Query Parameters: | |
|---|---|
| extra_fields | Extra fields to include in the response. See the Extra Fields section for details. |
| num_results_only | Just return the number of results (in the metadata) but not the actual results. |
Themes
Themes can be searched within documents or organisations by using either: the theme object_id or category_id e.g. C470
https://api.ids.ac.uk/openapi/eldis/search/organisations/?theme=C470
or the theme object string (comprised of the theme object_id | object_type | theme object_name) e.g. C470|full|gender
https://api.ids.ac.uk/openapi/eldis/search/documents/?theme=C470|theme|gender
or the theme path (comprised of the theme names, delimited by a full stop. This is deprecated as theme titles are liasble to change over time e.g. “Climate change.International climate change negotiations”
https://api.ids.ac.uk/openapi/eldis/search/documents/?theme=Climate change.International climate change negotiations
Countries
Note: The country of focus detemines either a document’s country of focus or the countries in which an organisation works. Countries can be searched within documents or organisations by using either: the country object_id or 2-letter iso code e.g. A1000 or AF
https://api.ids.ac.uk/openapi/eldis/search/documents/?country=A1000
https://api.ids.ac.uk/openapi/eldis/search/documents/?country=AF
or the country name (as these are unique) e.g, Burkina Faso
https://api.ids.ac.uk/openapi/eldis/search/documents/?country=Burkina%20Faso
or the country object string (comprised of the country object_id | object_type | country object_name | iso code ) e.g. A1000|country|Afghanistan|AF
https://api.ids.ac.uk/openapi/eldis/search/documents/?country=A1000|country|Afghanistan|AF
Document specific query fields:
These fields are only valid when searching for documents, ie when the URL starts with /openapi/search/documents/.
| Query Parameters: | |
|---|---|
| author | The author(s) of the document. |
| publisher | The Object Id or full object string for the publisher. This is the same as an organisation id. e.g. ?publisher=A3454 |
| publisher_name | A text string to match on part of the publisher name |
| publisher_country | The country where the publisher is located. |
| copyright_clearance | Whether the copyright holder has given permission for ELDIS to host the information. |
| redistribute_clearance | Whether the copyright holder has given permission for the information to be redistributed. |
| language_name | The language the document is written in. |
| document_published_after | Date after which the document was published. |
| document_published_before | Date before which the document was published. |
| document_published_year | The document was published during the specified year. |
For the document_published_after and document_published_before fields, the date should be specified as YYYY-MM-DD (year, month, day). For the document_published_year field, the value is just the 4 digit year.
Organisation specific query fields:
These fields are only valid when searching for organisations, ie when the URL starts with /openapi/search/organisations/.
| Query Parameters: | |
|---|---|
| acronym | The acronym for an organisation. |
| organisation_name | The name of an organisation. |
| location_country | The country in which the organisation is located |
Category specific query fields:
These fields are only valid when searching within themes, ie when the URL starts with /openapi/search/themes/.
| Query Parameters: | |
|---|---|
| level | The level of the category with the hierarchy (if applicable) |
| parent_object_id | The object_id of the direct parent category |
| toplevel_object_id | The object_id of the top-level parent |
| archived | Whether the category has been archived (‘true’ or ‘false’) |
Combining query fields and terms
Combining query fields
Query fields may be combined, so for example you may search for q=malaria and country=Angola. the query would be:
https://api.ids.ac.uk/openapi/eldis/search/documents/?q=malaria&country=angola&extra_fields=country_focus_array
Note that query fields are always ANDed together as they use the query string &.
Combining query terms
Within each query field you can combine terms using either AND or OR using the & and | characters respectively. These characters must be URL encoded. In this case & becomes %26 and | becomes %7C. e.g. To search for objects that are concerned with either Angola or Lesotho:
country=Angola|Lesotho(before being URL encoded)
https://api.ids.ac.uk/openapi/eldis/search/documents/?country=Angola%7CLesotho (after being URL encoded)
By default multiple search terms in the query parameters will be ORed together. i.e. the items returned will be those that match any of the search terms. For example:
https://api.ids.ac.uk/openapi/eldis/search/documents/?q=skill%20health%20 ozone
This will return all documents from Eldis which contain Skill OR Health OR Ozone. The items with both Skill and Health and Ozone will be returned first as the query will sort by relevance, by default (see below)
Notes
- You can only use one of either AND or OR within a single query parameter or you may get unexpected results.
- Phrase searches are currently not supported.
- Exclusion (NOT) searches are not supported.
Note that this means that if you include a space (URL encoded as %20) the terms will be considered separate words. So q=climate%20change will search for anything containing “climate” OR “change”.
Using the q field (special case)
To allow users to search for query terms directly, for example using a search box on a form, we allow the special word “and” and “or” to be used in the search string. These are interpreted as AND and OR as per the & and | characters above. For example, the following query will search for items that are concerned both with either Angola or South Africa, and contain either either gender or climate or change.
country=Angola|South Africa & q=gender or climate change (before being URL encoded) country=angola%7Csouth%20africa&q=gender%20or%20climate%20change (after being URL encoded)
Notes
- Make sure you encode each query parameter value separately and then combine them, rather than combining them and then encoding the whole query string.
- Don’t encode the = characters.
For the above example you could encode the URL with (in pseudo-code):
url = url_root + 'objects/search/?'
url += 'country=' + url.encode('angola&lesotho')
url += 'theme=' + url.encode('gender|climate change')
Sort Order
For general q= searching, the results are returned in relevance rank order. For all other searches the default sort order is date_created descending, which displays the most recently added object first. Sort order may be overridden, using the following parameters
| Query Parameters: | |
|---|---|
| sort_asc | Sort by the field named, in ascending order. |
| sort_desc | Sort by the field named, in descending order. |
The fields which may be used for sorting are:
- title
- name
- object_id
- publication_date
- date_created
Note that you can only use one of sort_asc and sort_desc, and only once.
Get an alphabetic list of Eldis documents where the publishers name contains the word "Oxfam" https://api.ids.ac.uk/openapi/eldis/search/documents/?publisher_name=oxfam&sort_asc=title&extra_fields=publisher Get the oldest BRIDGE documents which contain the word Malawi https://api.ids.ac.uk/openapi/bridge/search/documents/?q=malawi&sort_asc=date_created&extra_fields=date_created
Pagination
| Query Parameters: | |
|---|---|
| num_results | The number of results to return. If not specified then a value of 10 is used. |
| start_offset | The index of the result to start from. If not specified then a value of 0 is used. |
https://api.ids.ac.uk/openapi/eldis/search/organisations/?q=governance&num_results=100 https://api.ids.ac.uk/openapi/eldis/search/organisations/?q=governance&start_offset=50
Note that the metadata section of the results will have links to the next and previous pages (assuming they exist). Also the maximum value for num_results is 500.