We encourage developers to link to our site. You can do this by either copying the URL from the Address Bar or constructing your own API/URL (see below). We do request that you create links directly to our site and do not frame the Bank's page with your own site banner.
We now have a new and improved way of linking to document profiles and results. See documentation and examples below.
Documents & Reports (D&R) Invariant API
Documents & Reports (D&R) will support simplified URLs for two kinds of pages: results pages and document profile pages. We will make sure we support the invariant API even if D & R moves to a new platform in the future, so users don't need to change their URLs linking to our documents.
URLs for these pages have three parts. These parts together determine (1) which application to handle the request, (2) the type of page to be returned, and (3) the document or set of documents to be presented on that page.
These three parts together take the following form.
http:///?
Host name
In technical terms, the first part of the URL names the host. The host name will be “documents.worldbank.org”.
Type of request
The page is to be returned, the second part of the URL, is determined by the type of request. The request type will be either “record” or “query”. A “record” request will return the profile (or data record) belonging to an individual document. A “query” request will return a set of documents that match that query.
| Request type | Page returned |
|---|---|
| record | Complete profile for an individual document with one or more links to the document itself. |
| query | A query defining a set of documents presented as a list or table. |
Parameter list
The third and last part of the URL consists of one or more parameters and their values. These parameters and values specify the document or set of documents presented on the page. The list of parameters and their values is separated from the request type that precedes it by the “?” character.
”Record” requests have a single, required, parameter, “docid”, whose value is the ImageBank or D&R identifier for the profile document to be displayed on the page. The parameter name, “docid”, is separated from its value by the “=” sign.
In addition to the docid parameter, record requests also support an optional parameter, pageLanguage. This parameter determines the language of the page displaying the record and can be used by non-English sites to present ImageBank documents in the language of the site. At present, requests for French, Spanish, Chinese, Arabic and Russian are supported.
| Parameter name | Use |
|---|---|
| docid | D&R ID for the document whose profile is to be returned. |
| pageLanguage | The language of the page displaying the record. Please use the following two-letter language codes: ar (Arabic), zh (Chinese), ru (Russian), es (Spanish), fr (French). |
Here is an example:
documents.worldbank.org/record?docid=000160016_20040929135419
“Query” requests are requests for a set of documents presented as a list on the page returned. Query requests may have one or more parameters. Each additional parameter more tightly specifies or restricts what is to be returned. These parameters correspond to an attribute in a document’s record or profile. Each parameter name is separated from its value by an “=” sign. When more than one parameter / value pair is used, each new pair is separated from the previous by the “&” character. No “&” character is placed before the first pair. To query on more than one value for an attribute, either include additional parameter / value pairs for that attribute (each having a single value), or use the parameter name once and list the values, separating the values by a space. Querying on multiple values for an attribute increases the number of documents returned since documents for each value passed can be included in results.
Like record requests, query requests may also specify the language of the page displaying results. French, Spanish, Chinese, Arabic and Russian are supported currently.
| Parameter name | Value | Use |
|---|---|---|
| text | text | one or more words |
| title | text | the title of the document |
| collection | text | the title of the collection to which the document belongs |
| sourceCitation | Text | the source citation |
| author | text | an author of the document |
| region | text or ID | the region to which the document belongs |
| country | text or ID | the country to which the document belongs |
| sector | text or ID | the sector to which the document belongs |
| subsector | text or ID | the subsector to which the document belongs |
| topic | text or ID | a topic addressed by the document |
| majorDocType | text or ID | the major document type to which the document belongs |
| docType | text or ID | the document |
| language | text or ID | the language in which the document is written or translated |
| date | yyyy/mm/dd | the date the document was submitted or published |
| startDate | yyyy/mm/dd | the beginning of a date range. Documents returned must be submitted or published on or after this date. It can be used with or without endDate. When endDate is not used, then the range ends with the present. |
| endDate | yyyy/mm/dd | the end of a date range. Documents returned must be submitted or published on or before this date. It can be used with or without startDate. When startDate is not used, then the range includes all dates prior to this present. |
| report | ID | the report number assigned to this document |
| loan | ID | the number of the loan to which this document belongs |
| credit | ID | the credit number associated with this document |
| project | text or ID | the name or ID of the project to which this document belongs |
| trustFund | ID | the trust fund with which this document is associated |
| pageSize | number | The number of results to display per page (up to 50) |
| pageLanguage | ID | the language of the page displaying the record.French and Spanish are currently supported. |
| sortBy | the attribute (“date”, “title”, “report”, or “docType”) by which results should be sorted. Sorting is in ascending order except for date, which is in descending order. |
Following are some examples:
To list documents on a single topic...
documents.worldbank.org/query?topic=Education
To list documents related to a single topic and country…
documents.worldbank.org/query?country=China&topic=Education
To return all documents published or released on an exact date...
documents.worldbank.org/query?date=2004/2/4
To return all documents published or released on a topic published or released between two dates...
documents.worldbank.org/query?startDate=2004/1/1&endDate=2004/2/1&topic=Agriculture
To return all documents in Arabic...
documents.worldbank.org/query?language=Arabic
To return all documents based on Unit owning,
documents.worldbank.org/query?owner_exact=Development+Committee+(DCS)