Calling the API > Search

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

Queries

Results

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:

  • Object Id
  • 2 character ISO code
  • Country name
keyword The name of a keyword to search for.
region One of:

  • Object (region) Id
  • Region object
  • Region name
theme One of:

  • Object (category) Id
  • Theme object
  • Theme path
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:

http://api.ids.ac.uk/openapi/eldis/search/assets/?q=undp 

http://api.ids.ac.uk/openapi/bridge/search/documents/?country=Angola

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

http://api.ids.ac.uk/openapi/eldis/search/documents/?keyword=af* 

http://api.ids.ac.uk/openapi/eldis/search/documents/?keyword=af*ca

but not:

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

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

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

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

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

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

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

http://api.ids.ac.uk/openapi/eldis/search/documents/?country=A1000
http://api.ids.ac.uk/openapi/eldis/search/documents/?country=AF

or the country name (as these are unique) e.g, Burkina Faso

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

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

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

http://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"
http://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
http://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.
http://api.ids.ac.uk/openapi/eldis/search/organisations/?q=governance&num_results=100

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


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.