Geoname Service (API)

Description

The Canadian GeoNames Search Service allows users to search for current and formerly official geographical names found in the Canadian Geographical Names Data Base (CGNDB) through an Application Programming Interface (API). The CGNDB is Canada’s national authoritative geographical name database. The API is a tool to query the CGNDB using Uniform Resource Identifiers (URIs) like those seen below. Such URIs may be inserted into your Web pages or applications and allow searches by:

• geographical name
• unique key
• coordinates
• alphabetical list

Content advisory: The Canadian Geographical Names Database contains historical terminology that is considered racist, offensive and derogatory. Geographical naming authorities are in the process of addressing many offensive place names, but the work is still ongoing. For more information, please contact the GNBC Secretariat.

Request Parameters

The service accepts a series of parameters allowing narrowing the selection or filtering the list of requested geographical names. Parameters are summarized in the following table. All parameter values must be URL encoded.

Parameter	Description
q	Search terms. This parameter is case insensitive and unaccented characters can be substituted for accented characters without affecting results. It supports usage of wildcards (*) when searching for all terms starting with provided characters.
bbox	This parameter is used to restrict the list to geographical names within or partially within the bounding box selected by the user. A bounding box is created by using comma-separated ordinate values in decimal degree numeric format corresponding to the west, south, east and north bounds of the area. For example:  bbox=-72.0,44.5,-69.5,45.5.
lat	This parameter, represented by the latitude of a location expressed in decimal degrees, is used in conjunction with the lon parameter in order to search for geographical names located within a certain proximity to a specific geographical location.
lon	This parameter is used in conjunction with the lat parameter in order to search for geographical names within a certain proximity to a specific geographical location. The longitude of the location is expressed in decimal degrees.
radius	This parameter, the length of a search radius around selected geographical location expressed in kilometres, is used in conjunction with lat and lon parameters in order to search for geographical names within a specific radius. It accepts an integer between 1 and 100. The default value is 10.
category	Filter on the status category of the geographical names. Allowed values are the following: O : Official names H : Formerly official names
theme	Filter the selection based on the feature type category of the geographical names. A list of supported values is available at the following location: https://geogratis.gc.ca/services/geoname/en/codes/theme
concise	Filter the selection based on the feature type of the geographical names. A list of supported values is available at the following location: https://geogratis.gc.ca/services/geoname/en/codes/concise
province	Filter the selection based on the province or territory where the geographical names are located. A list of supported values is available at the following location: https://geogratis.gc.ca/services/geoname/en/codes/province
sort-field	Name of the property on which the sorting of the result set will be performed. Allowed values are the following: name: name of the geoname distance: distance from the position submitted (latitude and longitude request parameter values) concise: feature type of the geoname province: province or territory where the geonames are located
num	This parameter indicates the number of records to display. It accepts an integer between 1 and 1,000. If the value exceeds the maximum limit, the maximum limit will be used instead of the provided value. The default value is 100.
skip	This parameter indicates the number of records to skip before presenting the first item in the result set. It accepts a positive integer and the default value is 0. To be used in combination with the sort-field parameter to ensure the results are always returned in the same order.
exclude	List of properties to exclude from the response.
expand	List of linked properties to include in the response.
select	List of sub-properties from linked properties to include in the response.
callback	Name of the callback function used into JSONP format (JSON with padding) allowing support for asynchronous and cross-domain invocation of the service through JavaScript applications.

Examples of Requests

Search with terms:
https://geogratis.gc.ca/services/geoname/en/geonames?q=anticosti

Search with terms using wildcard:
https://geogratis.gc.ca/services/geoname/en/geonames?q=montr*

Search with terms using filter on status category:
https://geogratis.gc.ca/services/geoname/en/geonames?q=ottawa&category=H

Search with terms using filter on feature type category:
https://geogratis.gc.ca/services/geoname/en/geonames?q=vancouver&theme=984

Search with terms using filter on feature type:
https://geogratis.gc.ca/services/geoname/en/geonames?q=vancouver&concise=CITY

Search with terms using filter on province or territory code:
https://geogratis.gc.ca/services/geoname/en/geonames?q=ottawa&province=24

Search with terms with sorting on name:
https://geogratis.gc.ca/services/geoname/en/geonames?q=montreal&sort-field=name

Search by bounding box:
https://geogratis.gc.ca/services/geoname/en/geonames?bbox=-72.0,45.5,-71.5,46.0

Search by coordinates with radius search:
https://geogratis.gc.ca/services/geoname/en/geonames?lat=45.5&lon=-71.5&radius=50

Search by coordinates with sorting on distance:
https://geogratis.gc.ca/services/geoname/en/geonames?lat=45.5&lon=-71.5&sort-field=distance

Example of responses

The service returns a list of matching geographical names corresponding to the provided search criteria. The response usually includes attributes describing the geographical name and links to related web resources.

Supported Representations

Responses can be provided in various formats. The default format is JSON but other types of representations can be invoked by specifying the suitable format in the request Accept header, or by adding the appropriate file extension to the request URI. Supported formats available for each web resource are variable. The following table summarizes the main supported formats as well as accepted media types and their associated extension.

Format	Media Types	URI extensions
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

Examples of requests to get different representations

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

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

Other examples of requests

Get a geoname by CGNDB Key:
https://geogratis.gc.ca/services/geoname/en/geonames/EGNMO

Get a list of geonames by Toponymic Feature ID:
https://geogratis.gc.ca/services/geoname/en/features/8c26e83bba3611d892e2080020a0f4c9

Get the list of province codes:
https://geogratis.gc.ca/services/geoname/en/codes/province

Get the list of concise codes:
https://geogratis.gc.ca/services/geoname/en/codes/concise

Get the list of generic codes:
https://geogratis.gc.ca/services/geoname/en/codes/generic

Get the list of status codes:
https://geogratis.gc.ca/services/geoname/en/codes/status