Geolocation Service

Description

The Geolocation service allows end users to get the geographic location of named features. The current service allows the location of following features:

• Street addresses
• Street names
• Streets intersection
• Place names located in Canada such as towns, villages, municipalities, parks, etc, but also of natural geographical features such as lakes, islands, rivers, mountains, etc.
• Postal codes (FSA code only - first three characters)
• Map numbers from the National Topographic System (NTS)

Request Examples

The service accepts a single parameter named q corresponding to the terms to be localized. Here are query samples for each feature types.

• Street address (excluding postal code): http://geogratis.gc.ca/services/geolocation/en/locate?q=2144%20King%20West%20Street,%20Sherbrooke,%20QC
• Street name: http://geogratis.gc.ca/services/geolocation/en/locate?q=King%20West%20Street,%20Sherbrooke,%20QC
• Intersection: http://geogratis.gc.ca/services/geolocation/en/locate?q=King%20West%20Street,%20Farwell%20Street,%20Sherbrooke,%20QC
• Place name: http://geogratis.gc.ca/services/geolocation/en/locate?q=Sherbrooke,%20QC
• Postal Code: http://geogratis.gc.ca/services/geolocation/en/locate?q=J1J
• NTS number: http://geogratis.gc.ca/services/geolocation/en/locate?q=021e

Request Parameters

Request Parameters are summarized in the following table. All parameter values need to be URL encoded.

Wildcard Search

The q parameter also supports asterisk (*). Those allow to find any terms starting with the provided characters.

http://geogratis.gc.ca/services/geolocation/en/locate?q=Otta*

Response Examples

The service returns a list of locations related to the requested terms, each element includes the Type of the location and a Point geometry with coordinates expressed as longitude/latitude in decimal degrees. In some cases, a bbox property is also included and contains coordinates of the bounding box for the feature's geometry. Results are sorted by relevancy.

Responses are in JSON format. It is also possible to provide a value to the callback parameter in order to receive a response wrapped into a function call. This is useful for asynchronous and cross-domain invocations of the service form applications hosted on distinct domains.

[
...
{
    "title": "Ottawa, Carleton; Russell, Ontario (City)", 
    "qualifier": "LOCATION",
    "type": "ca.gc.nrcan.geoloc.data.model.Geoname",
    "bbox": [-76.3555857, 44.9617738, -75.2465783, 45.5376514],
    "geometry": {"type":"Point","coordinates":[-75.58429,45.333389]}
},
...
{
    "title": "031G05 OTTAWA", 
    "qualifier": "LOCATION",
    "type": "ca.gc.nrcan.geoloc.data.model.NTS",
    "bbox": [-76.0, 45.25, -75.5, 45.5],
    "geometry": {"type":"Point","coordinates":[-75.75,45.375]}
},
...
{
    "title": "Ottawa Avenue, Brandon, Manitoba", 
    "qualifier": "INTERPOLATED_CENTROID",
    "type": "ca.gc.nrcan.geoloc.data.model.Street",
    "geometry": {"type":"Point","coordinates":[-99.9691476,49.8254685]}
},
...
]

Additional Functionalities

As experimental work, the Geolocation service offers two additional functionalities allowing a suggestion of similar terms or an auto-completion. These two functions take only one term at a time.

Suggestion of similar terms

The Suggestion functionality provides the opportunity to obtain terms having phonetic or syntactic proximity with a given term. The terms are sorted by frequency of appearance of the suggested term in the index. However if the provided term already exists in the index, it will be proposed first.

http://geogratis.gc.ca/services/geolocation/fr/suggest?q=Sherbrooke

Auto-completion

The Auto-complete functionality provides the opportunity to obtain terms starting with a given character string. The terms are sorted by frequency of appearance of the suggested term in the index. However if the provided character string exactly correspond to a term in the index, this term will be proposed first.

http://geogratis.gc.ca/services/geolocation/fr/autocomplete?q=Sherb