Service de toponymie (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

Mise en garde: La base de données toponymiques du Canada contient des termes historiques considérés comme racistes, offensants et péjoratifs. Les autorités de dénomination géographique travaillent actuellement à l'élimination de nombreux toponymes offensants, mais le travail est toujours en cours. Pour obtenir plus de renseignements, veuillez communiquer avec le secrétariat de la CTC.

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 : https://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 : https://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 : https://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 retourner le premier item de la liste. Il reçoit un nombre entier positif et la valeur par défaut est 0. À utiliser en combinaison avec le paramètre sort-field afin que les résultats soient toujours retournés dans le même ordre.
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 :
https://geogratis.gc.ca/services/geoname/fr/geonames?q=anticosti

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

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

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

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

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

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

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

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

Recherche par coordonnées avec tri par distance :
https://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 types de médias 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
GEOJSON	application/vnd.geo+json	.geojson

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

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

CSV :
https://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 :
https://geogratis.gc.ca/services/geoname/fr/geonames/EGNMO

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

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

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

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

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