The World Bank Documents & Report API

The World Bank offers an API that allows for the search and retrieval of the public, Bank documents available in the Documents & Reports site.  Records can be retrieved in a format useful for research and for inclusion in web sites outside of Documents & Reports and the World Bank. 

Overview (A Simple Example)

The API is offered much like a REST API, accepting requests in the form a URL’s query string as HTTP GET requests.   The URL’s query string determines:

·        what is to be searched

·        what is to be returned for each matching record

·        how what is returned is formatted (as JSON or XML)  

What follows is a simple request querying for records of documents related to wind turbines.  It also requests that the list returned be in a JSON format and that the country and document date be returned with each record.  (Other key, record fields, like display title and URL, are always returned):

https://search.worldbank.org/api/v3/wds?format=json&qterm=wind%20turbine&fl=docdt,count

The query for matching records is given as the value of the “qterm” parameter. 

The format for results is given as the value of the format parameter, “format”.  Either “json” or “xml” can be requested. 

The fields to be returned are given as a comma separated list with the “fl” parameter.

How to Query

The example above illustrates the use of the “qterm” parameter.  Queries given with the qterm parameter will return all records matching that query in one of more of its fields.   So when querying with “qterm”, a record will be a match if words from the query appear in the document’s title, its abstract, report number, or associated project number or project name, its associated country, region or any of a number of other, core fields.  

You can further restrict matches to specific fields by using the URL query string parameters in the list at the end of this article (by passing the values to be matched as their values).   Those fields are marked “Yes” in the “Query parameter” column of the table.  This request will return all records whose display titles contain both the words “wind” and “energy”.   

https://search.worldbank.org/api/v3/wds?format=json&display_title=wind%20energy

You’ll see many field names end in “_exact”.   The values passed for those parameters must exactly match the value of the field in the document corresponding to that parameter if the field is to be considered a match to the query.   

How to Request the Return of Specific Fields

You can request the fields to be returned for each record using the URL query string parameter name, “fl”.   More than one field can be requested by listing fields in a comma separated list.  The following query for all records listing Algeria in their country fields requests the return with each record of the record’s list of countries, its volume number, total number of volumes, document name and report name. 

https://search.worldbank.org/api/v3/wds?format=xml&count_exact=Algeria&fl=count,volnb,totvolnb,docna,repnme

You can request any field marked “Yes” as retrievable in the table at the end of this article. 

How to Retrieve Facets

All values found for a field across all documents returned for a query can be listed if the field is available as a facet.   The fields for which facets are requested are passed as a comma separated list with the “fct” parameter.  For example, the following lists all values for country and language (the “count_exat” and “lang_exact” fields) in an XML format. 

https://search.worldbank.org/api/v3/wds?format=xml&fct=count_exact,lang_exact&rows=0

Since no query is specified as a filter, all records are considered a match.  This request also requests no rows be returned with results to make locating the facet’s list of values easy to spot in the XML returned.  (The use of “rows” is documented in “How to Page Through Results” below.)

How to Page through Results

Two URL query string parameters control how large each returned page of matching records will be and where that page is in the overall set of results.   The number of records on a page is requested using the “rows” parameter.  Which record should start that page is requested with the “os” parameter.  The first record in the entire record set is referred to a record “0”.  So, to request the first page of results and request a page size of 20, you would send the following request:

https://search.worldbank.org/api/v3/wds?format=json&rows=20&os=0&fl=docty

There is no query in this example.  So all records are considered a match.  The document type field, “docty”, will also be returned for each result. 

To return records, 40 through 60 (equivalent to page 3 when the page size is 20), the following request would be sent:

https://search.worldbank.org/api/v3/wds?format=json&rows=20&os=40&fl=docty

The default value for rows is 10 and the default value for os is 0.   So to request the first page of results, using “os” is not required.  And if 10 results per page are enough, “rows” is not required. 

More Advanced Queries

When more than one query field appears in a query, all records must match the query given for each field.  For example, if “energy” is given as the value for the query parameter, “qterm”, and “water” is given as the value for “display_title”, then all records with a field containing the value “energy” whose title contains “water” will be returned.

https://search.worldbank.org/api/v3/wds?format=json&qterm=energy&display_title=water&fl=display_title&rows=20&os=100

The above query is also requesting 20 records starting at record 100, requesting records be returned in the JSON format and requesting that each record include the display_title field.

If the value of a field is usually a single number or code (or a list of numbers or codes) or if the field is an “_exact” field, then a query can be formed to match all records having any value in a list of values by separating those values with the separator, “%5E” (the character, “^”, encoded to safely appear in a URL).   The following requests all records whose country field lists either the Russian Federation or Armenia and whose language is Russian or French.   The first 10 results are requested along with facet values for country (“count_exact”) and language (“lang_exact”).  

https://search.worldbank.org/api/v3/wds?format=xml&fct=count_exact,lang_exact&rows=10&count_exact=Russian%20Federation^Armenia&lang_exact=Russian^French

Remember that the country field, and many other fields, can have more than one value.   So Armenia, for example, may appear listed with other countries for a record.  Because those records match, all its countries will also be among the countries listed for the country facet, “count_exact”.   So, while we queried for the Russian Federation and Armenia, other countries can be listed in the countries facet (“count_exact”). 

If a field is available as a facet and as a query parameter, you can use that field to query on one or more of the values listed for that facet.  The query above illustrates this for count_exact and lang_exact. 

Date Range Queries

To query for all documents newer than a specific date, you would use the “strdate” parameter.  To query for all documents older than a specific date, you would query with the “enddate” parameter.  The format for dates can be either “YYYY-MM-DD” or “MM-DD-YYYY”.  The following requests all procurement plans newer than January 1, 2018. 

https://search.worldbank.org/api/v3/wds?format=json&os=40&fl=docdt,docty&strdate=2018-01-01&docty_exact=Procurement+Plan

The following further restricts results to those older than March 30 of that year:

https://search.worldbank.org/api/v3/wds?format=json&os=40&fl=docdt,docty&strdate=2018-01-01&enddate=2018-03-30&docty_exact=Procurement+Plan

Sorting Results

By default, results are sorted by relevance when “qterm” is used.  Otherwise, results are sorted by document date in descending order.  

To sort by another field, you would pass its name with the “srt” parameter and specify an ascending sort by specifying “asc” as the value of the “order” parameter or specify a descending order by passing “desc”. 

To force a request in ascending order by document date, you would send the following request.  

https://search.worldbank.org/api/v3/wds?format=json&os=40&fl=docdt,docty&strdate=2018-01-01&enddate=2018-03-30&docty_exact=Procurement+Plan&sort=docdt&order=asc

URL Querying String Parameters and Fields