Nous encourageons les développeurs comme vous à pointer vers notre site. Vous pouvez pour cela copier l’URL à partir de la barre d’adresse, ou bien construire votre propre API/URL (voir ci-dessous). Ce que nous vous demandons, c'est de créer seulement des liens qui renvoient directement à notre site, et de ne pas incorporer la page de la Banque sous la bannière de votre propre site.
Nous avons défini une nouvelle et meilleure façon de créer des liens vers les profils et résultats pour nos documents et rapports. Voyez la documentation et les exemples ci-dessous.
API fixe – Documents et Rapports (D&R)
Notre site Documents et rapports (D&R) supportera les URL simplifiées pour deux types de pages : les pages de résultats, et les pages de profils de documents. Nous veillerons à supporter l’API de type invariant même si les D&R passent sur une nouvelle plateforme à l’avenir, pour que les utilisateurs n’aient pas à changer leurs URL pointant vers nos documents.
Les URL pour ces pages comportent trois parties, qui définissent ensemble les éléments suivants : 1) par quelle application la demande doit être traitée ; 2) le type de page qui doit être généré ; et 3) le document ou la série de documents qui doit apparaître sur la page en question.
L’ensemble de ces trois parties se présente sous la forme suivante :
http:///?
Nom d’hôte
Techniquement parlant, la première partie de l’URL désigne l’hôte. En l’occurrence, le nom d’hôte sera «documents.banquemondiale.org».
Type de demande
La deuxième partie de l’URL, correspondant au type de page devant être généré, est fonction du type de demande. La demande sera du type «record» ou «query». Une demande de «record» produira le profil (ou registre de données) correspondant à un document particulier. Une demande de «query» produira une série de documents correspondant à cette requête.
| Type de demande | Résultat de la demande |
|---|---|
| record | Profil complet pour un document particulier, comportant un ou plusieurs liens vers le document proprement dit. |
| query | Série de documents présentée sous forme de liste ou de tableau. |
Liste de paramètres
La troisième et dernière partie de l’URL comprend un ou plusieurs paramètres et les valeurs qui s’y rattachent. Ce sont ces paramètres et valeurs qui déterminent le document ou la série de documents qui apparaîtra sur la page. La liste des paramètres et des valeurs correspondantes est séparée du type de demande qui la précède par le caractère « ? ».
Une demande de type «record» a un seul paramètre exigé, «docid», dont la valeur est l’identificateur ImageBank ou D&R pour le document dont le profil doit apparaître sur la page. Le nom de ce paramètre («docid») est séparé de sa valeur par le signe « = ».
En plus du paramètre docid, les demandes de registre peuvent aussi accepter un paramètre optionnel, « pageLanguage ». Ce paramètre détermine la langue de la page sur laquelle apparaîtra le registre, et peut servir aux sites de langue autre que l’anglais pour présenter les documents ImageBank dans la langue du site. À l’heure actuelle, le système supporte deux autres langues, à savoir le français et l’espagnol.
| Nom du paramètre | Utilisation |
|---|---|
| docid | Identificateur D&R pour le document dont le profil doit apparaître sur la page. |
| pageLanguage | Langue de la page sur laquelle apparaît le registre. Cette fonction n’est pas encore disponible. |
Voici un exemple d’URL et de ses composantes :
documents.banquemondiale.org/record?docid=000160016_20040929135419
Une demande de type «Query» porte sur une série de documents qui apparaîtra sous forme de liste sur la page générée par la demande. Elle peut comporter un ou plusieurs paramètres. Chaque paramètre successif sert à définir ou limiter plus précisément ce qui doit s’afficher sur la page. Les paramètres en question correspondent aux différents attributs figurant dans un registre ou profil de document. Le nom de chacun est séparé de sa valeur par le signe « = ». Si plus d’une paire paramètre/valeur est utilisée, chaque paire successive est séparée de la précédente par le caractère « & », étant entendu que la première paire n’est pas précédée du caractère « & ». Pour effectuer une requête sur plus d’une valeur pour un attribut, il y a lieu soit d’inclure les paires paramètre/valeur supplémentaires pour cet attribut (chacune comportant une seule valeur), soit d’utiliser une fois le nom du paramètre et de le faire suivre des valeurs, séparées les unes des autres par un espace. Une requête effectuée sur de multiples valeurs pour un certain attribut aura pour effet de multiplier le nombre de documents inclus dans le résultat de la demande, puisque les documents correspondant à chaque valeur incluse pourront figurer dans ce résultat.
Like record requests, query requests may also specify the language of the page displaying results. French and Spanish are supported currently.
| Nom du paramètre | Valeur | Utilisation |
|---|---|---|
| text | text | un ou plusieurs mots |
| title | text | titre du document |
| collection | text | titre de la collection dont fait partie le document |
| sourceCitation | Text | extrait du texte d’origine |
| author | text | l’auteur (ou l’un des auteurs) du document |
| region | text or ID | région à laquelle se rattache le document |
| country | text or ID | pays auquel se rattache le document |
| sector | text or ID | secteur auquel se rattache le document |
| subsector | text or ID | sous-secteur auquel se rattache le document |
| topic | text or ID | thème sur lequel porte le document |
| majorDocType | text or ID | principale catégorie de documents dont fait partie le document |
| docType | text or ID | document lui-même |
| language | text or ID | langue dans laquelle le document a été rédigé ou traduit |
| date | yyyy/mm/dd | date de soumission ou de publication du document |
| startDate | yyyy/mm/dd | début d’une série de dates ; les documents figurant dans le résultat de la demande auront été soumis ou publiés à ou après cette date ; peut s’accompagner d’une « endDate » (fin de série) ou non ; dans ce dernier cas, c’est la date présente qui clôt la série de dates |
| endDate | yyyy/mm/dd | fin d’une série de dates ; les documents figurant dans le résultat de la demande auront été soumis ou publiés à ou avant cette date ; peut s’accompagner d’une « startDate » (début de série) ou non ; dans ce dernier cas, la série inclut toutes les dates antérieures à la date présente. |
| report | ID | numéro de rapport assigné au document |
| loan | ID | numéro du prêt auquel se rattache le document |
| credit | ID | numéro du crédit auquel se rattache le document |
| project | text or ID | nom ou identificateur du projet auquel auquel se rattache le document |
| trustFund | ID | fonds fiduciaire auquel se rapporte le document |
| pageSize | number | nombre de résultats à afficher par page (jusqu’à 50) |
| pageLanguage | ID | langue de la page sur laquelle apparaît le registre ; à l’heure actuelle, le système supporte le français et l’espagnol. |
| sortBy | attribut (« date », « title », « report » ou « docType ») devant servir à trier les résultats de la demande ; le tri se fait par ordre ascendant hormis pour la date, où il se fait par ordre descendant |
Quelques exemples explicatifs figurent ci-dessous :
Pour afficher les documents sur un thème donné…
documents.banquemondiale.org/query?topic=Education
Pour afficher les documents se rapportant à un thème et un pays donnés…
documents.banquemondiale.org/query?country=China&topic=Education
Pour afficher tous les documents soumis ou publiés à une certaine date…
documents.banquemondiale.org/query?date=2004/2/4
Pour afficher tous les documents sur un thème donné soumis ou publiés entre deux dates…
documents.banquemondiale.org/query?startDate=2004/1/1&endDate=2004/2/1&topic=Agriculture
Pour afficher tous les documents en arabe…
documents.banquemondiale.org/query?language=Arabic