Documents & Reports

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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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

Parameter / field name

Description

Query parameter

Retrievable (with “fl”)

Facetable

Sortable

abstracts

Abstract (document summary)

 

Yes

 

 

admreg

Administrative Region in the Bank

 

Yes

Yes

 

admreg_exact

Administrative Region in the Bank

Yes

 

 

 

authr

Author

Yes

Yes

 

 

alt_title

Alternate title (in language of document)

 

Yes

 

 

authr_exact

Author

Yes

 

 

 

available_in

Avaiable in (other language translatios)

 

Yes

 

 

bdmdt

 

 

Yes

 

 

chronical_docm_id

Alternate document ID

Yes

Yes

 

 

closedt

Closing date

 

Yes

 

 

colti

Collection / Series title

Yes

Yes

 

 

colti_exact

Collection / Series title

Yes

 

Yes

 

count

Country

Yes

Yes

 

 

count_exact

Country

Yes

 

Yes

 

countcode

Two letter ISO country code

Yes

 

 

 

countrycode_exact

Two letter ISO country code

Yes

 

 

 

credit_no

Credit Number

Yes

Yes

 

 

datee

Create date (of D&R record)

 

Yes

 

 

disclosure_date

Disclsoure date

 

Yes

 

 

disclstat

Disclosure status

Yes

Yes

 

 

disclstat_exact

Disclosure status

Yes

 

Yes

 

display_title

Title (Report name plus volume name)

Yes

Yes

 

 

display_title_exact

Title (Report name plus volume name)

Yes

 

 

 

docdt

Document date

 

Yes

 

Yes

docm_id

Alternate document ID

Yes

 

 

 

docna

Document name (volume name)

 

Yes

 

Yes

docna_exact

Document name (volume name)

Yes

 

 

 

docty

Document type

Yes

Yes

Yes

Yes

docty_exact

Document type

Yes

 

 

 

entityid

Alternate document ID

 

Yes

 

 

envcat

Environmental category

 

Yes

 

 

geo_reg

Geographic region

Yes

Yes

 

 

guid

Alternate document ID

Yes

Yes

 

 

historic_topic

Historic topic (legacy topic)

 

Yes

 

 

id

Document ID

Yes

Yes

 

 

isbn

ISBN

 

Yes

 

 

issn

ISSN

 

Yes

 

 

keywd

Keyword

Yes

Yes

 

 

keywd_exact

Keyword

Yes

 

 

 

lang

Language

Yes

Yes

 

 

lang_exact

Language

Yes

 

Yes

 

lndinstr

Lending instrument

Yes

Yes

 

 

loan_no

Loan number

Yes

Yes

 

 

majdocty

Major document type

 

Yes

 

 

majdocty_exact

Major document type

Yes

 

Yes

 

majtheme

Major theme

 

Yes

 

 

majtheme_exact

Major theme

Yes

 

Yes

 

ml_abstract

Multilingual abstract (in language of document)

 

Yes

 

 

origu

Originating unit in the Bank

Yes

Yes

 

 

owner

Owning unit in the Bank

Yes

Yes

 

 

owner_exact

Owning unit in the Bank

Yes

 

 

 

pdfurl

PDF URL (of document)

 

Yes

 

 

prdln

Product line (lending)

Yes

Yes

 

 

proid

Project ID

Yes

 

 

 

projn

Project Name

 

Yes

 

 

projectid

Project ID

Yes

Yes

 

 

publishtoextweb_dt

Publish to external web date

 

Yes

 

 

repnb

Report number

Yes

Yes

Yes

Yes

repnb_exact

Report number

Yes

 

 

 

repnme

Report name

Yes

Yes

 

 

seccl

Seurity classification

 

Yes

 

 

sectr_exact

Sector (economic)

Yes

 

Yes

 

src_cit

Source citation

Yes

Yes

 

 

subsc

Subsector

 

Yes

 

 

subtopic

Subtopic

 

Yes

 

 

subtopic_exact

Subtopic

Yes

 

Yes

 

teratopic

Topic (legacy)

Yes

Yes

 

 

teratopic_exact

Topic (legacy)

Yes

 

Yes

 

theme

Theme

 

Yes

 

 

theme_exact

Theme

Yes

 

Yes

 

topic

Topic

 

Yes

 

 

topic_exact

Topic

Yes

 

Yes

 

topic_name_exact

Topic

Yes

 

Yes

 

totvolnb

Total number of volumes

 

 

 

 

topicv3

Topic

Yes

Yes

 

 

trustfund

Trust fund

Yes

Yes

 

 

trustfund_exact

Trust fund

Yes

 

 

 

txturl

Test URL (of document)

 

Yes

 

 

url

URL (of record for document)

 

Yes

 

 

volnb

Volume number

 

Yes