Interface pour la programmation d'applications - API

Description

Le service de recherche toponymique permet aux utilisateurs d’interroger la Base de données toponymiques du Canada (BDTC) à l’aide d’un API (Application Programming Interface ), qu’il s’agisse d’un toponyme officiel ou historique. La BDTC est la base de données nationale de référence pour les toponymes canadiens. Un API est un outil qui permet d’interroger la BDTC en utilisant un « Uniform Resource Identifiers (URIs) » tels que ceux indiqués ci-dessous. Ces URIs peuvent être ajoutés sur vos pages Web ou dans vos applications et permettent d’effectuer des recherches à partir :

  • du nom du lieu recherché
  • d’une clé unique
  • de coordonnées
  • de listes alphabétiques

Paramètres de requête

Le service accepte une série de paramètres permettant de restreindre ou de filtrer les toponymes recherchés. Les paramètres sont résumés dans le tableau suivant. Toutes les valeurs des paramètres doivent être encodées sous forme d'URL.

Paramètre Description
q Terme de recherche. Ce paramètre est insensible aux majuscules et les caractères accentués peuvent être saisis sans accent. Il supporte l’utilisation des astérisques (*) permettant de rechercher tous les termes débutant par les caractères fournis.
bbox Ce paramètre est utilisé afin de restreindre la recherche aux toponymes chevauchant spatialement le polygone englobant fourni. Le polygone englobant est défini selon une liste de coordonnées en degrés décimaux correspondant aux limites ouest, sud, est et nord de la région voulue. Par exemple : bbox=-72.0,44.5,-69.5,45.5.
lat Ce paramètre est utilisé en combinaison avec le paramètre lon afin de restreindre la recherche aux toponymes situés à proximité d’un lieu. Ce paramètre représente la latitude de la coordonnée du lieu exprimée en degrés décimaux.
lon Ce paramètre est utilisé en combinaison avec le paramètre lat afin de restreindre la recherche aux toponymes situés à proximité d’un lieu. Ce paramètre représente la longitude de la coordonnée du lieu exprimée en degrés décimaux.
radius Ce paramètre est utilisé en combinaison avec les paramètres lat et lon afin de restreindre la recherche aux toponymes situés à proximité d’un lieu. Ce paramètre représente la distance en kilomètres du rayon de recherche autour du lieu. Il reçoit un nombre entier situé entre 1 et 100. La valeur par défaut est 10.
category Filtre sur la catégorie de statut du toponyme. Les valeurs permises sont les suivantes :
O : Toponymes officiels
H : Toponymes historiques
theme Filtre sur la catégorie de type d’entité associé au toponyme. Les valeurs permises sont disponibles à l’adresse suivante : http://geogratis.gc.ca/services/geoname/fr/codes/theme
concise Filtre sur le type d’entité associé au toponyme. Les valeurs permises sont disponibles à l’adresse suivante : http://geogratis.gc.ca/services/geoname/fr/codes/concise
province Filtre sur le type sur la province ou le territoire associé au toponyme. Les valeurs permises sont disponibles à l’adresse suivante : http://geogratis.gc.ca/services/geoname/fr/codes/province
sort-field

Nom de la propriété sur lequel le tri de l’ensemble des résultats sera effectué. Les valeurs autorisées sont les suivantes :

nom : nom du toponyme

distance : distance de la position soumise (valeurs des paramètres pour la latitude et longitude demandées)

concise : type d’entité du toponyme

province : province ou territoire où les toponymes sont situés

num Ce paramètre indique le nombre d'items à afficher. Il reçoit un nombre entier situé entre 1 et 1 000. Si la valeur fournie excède la limite maximale, la valeur maximale sera alors utilisée. La valeur par défaut est 100.
skip Ce paramètre indique le nombre d’items à ignorer avant de retenir le premier item de la liste. Il reçoit un nombre entier positif. La valeur par défaut est 0.
exclude Liste des propriétés à exclure de la réponse.
expand Liste des propriétés liées à inclure dans la réponse.
select Liste des sous-propriétés des propriétés liées à conserver dans la réponse.
callback Nom de la fonction de rappel utilisée pour le formatage en mode JSONP (JSON with padding) permettant l'invocation asynchrone du service à partir d’applications hébergées sur des domaines distincts.

Exemples de requêtes

Recherche par terme :
http://geogratis.gc.ca/services/geoname/fr/geonames?q=anticosti

Recherche par terme avec utilisation de caractère astérisques :
http://geogratis.gc.ca/services/geoname/fr/geonames?q=ile+ant*

Recherche par terme avec filtre sur la catégorie de statut :
http://geogratis.gc.ca/services/geoname/fr/geonames?q=ottawa&theme=H

Recherche par terme avec filtre sur la catégorie de type d’entité :
http://geogratis.gc.ca/services/geoname/fr/geonames?q=vancouver&theme=1

Recherche par terme avec filtre sur le type d’entité :
http://geogratis.gc.ca/services/geoname/fr/geonames?q=vancouver&concise=CITY

Recherche par terme avec filtre sur la province ou le territoire :
http://geogratis.gc.ca/services/geoname/fr/geonames?q=ottawa&province=24

Recherche par terme avec tri alphabétique :
http://geogratis.gc.ca/services/geoname/fr/geonames?q=montreal&sort-field=name

Recherche par rectangle englobant :
http://geogratis.gc.ca/services/geoname/fr/geonames?bbox=-72.0,45.5,-71.5,46.0

Recherche par coordonnées et rayon de recherche :
http://geogratis.gc.ca/services/geoname/fr/geonames?lat=45.5&lon=-71.5&radius=50

Recherche par coordonnées avec tri par distance :
http://geogratis.gc.ca/services/geoname/fr/geonames?lat=45.5&lon=-71.5&sort-field=distance

Exemples de réponses

Le service de recherche retourne une liste des toponymes correspondant aux critères de recherche fournis. Le résultat contient habituellement les valeurs des attributs décrivant chacun des toponymes ainsi que des liens vers les ressources web liés à celui-ci.

Types de représentation supportés

Les réponses aux requêtes peuvent être fournies dans divers formats. Le format par défaut est le format JSON mais d’autres types de représentations peuvent être obtenus en spécifiant le format désiré dans l’entête Accept de la requête ou en ajoutant une extension à l’URI invoqué. Les formats supportés au niveau des différentes ressources web exposées par le service de recherche peuvent être variables. Le tableau suivant contient une liste des principaux formats supportés ainsi que les media types et extensions reconnus.

Format Media Types Extension de l’URI
JSON application/json .json
HTML text/html .html
CSV text/csv .csv
KML application/vnd.google-earth.kml+xml .kml
GML application/gml+xml .gml
WKT text/wkt .wkt

Exemples de requêtes pour obtenir différentes représentations

JSON :
http://geogratis.gc.ca/services/geoname/fr/geonames.json?q=iqaluit

CSV :
http://geogratis.gc.ca/services/geoname/fr/geonames.csv?province=47&concise=CITY

Autres exemples de requêtes

Obtenir un toponyme à partir d’une clé BDTC :
http://geogratis.gc.ca/services/geoname/fr/geonames/EGNMO

Obtenir une liste de toponymes à partir d’un identificateur toponymique :
http://geogratis.gc.ca/services/geoname/fr/features/8c26e83bba3611d892e2080020a0f4c9

Obtenir la liste des codes de province :
http://geogratis.gc.ca/services/geoname/fr/codes/province

Obtenir la liste des codes concis :
http://geogratis.gc.ca/services/geoname/fr/codes/concise

Obtenir la liste des codes génériques :
http://geogratis.gc.ca/services/geoname/fr/codes/generic

Obtenir la liste des codes de statut :
http://geogratis.gc.ca/services/geoname/fr/codes/status