Application Programming Interface - 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

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: http://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: http://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: http://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. The default value is 0.
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:
http://geogratis.gc.ca/services/geoname/en/geonames?q=anticost

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

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

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

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

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

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

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

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

Search by coordinates with sorting on distance:
http://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
WKT text/wkt .wkt
GEOJSON application/vnd.geo+json .geojson

Examples of requests to get different representations

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

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

Other examples of requests

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

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

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

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

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

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