Application Programming Interface - API
API
The API is a technique to query the CGNDB using Uniform Resource Identifiers (URI) like those seen below. Such URI may be inserted into your Web pages or applications.
The API queries the CGNDB database through the WFS. The API was created to be simple to use, to validate requests, provide informative error messages, and return specific queries in a simple way. Examples and parameters follow. Here is a table of all the API parameters.
Note: With the WFS, you decide which columns from the CGNDB are returned. The API, on the other hand, always returns the same number of columns (fields). To get fewer columns, use the WFS.
1- Output Formats
Many output formats are available:
xml (Machine-readable Extensible Markup Language) (by default).
http://geonames.nrcan.gc.ca/api?geoname=toronto&output=xml
html (HyperText Markup Language) table.
The table may be pasted into a spreadsheet such as MS Excel. To remove the formatting, copy and paste it again using Paste Special.../Values (with no format).
http://geonames.nrcan.gc.ca/api?geoname=montreal&output=html
GML0, GML2 and GML3 (GIS-readable Geography Markup Language, version 0, 2 or 3)
http://geonames.nrcan.gc.ca/api?geoname=halifax&output=GML3
KML (Keyhole Markup Language)
http://geonames.nrcan.gc.ca/api?geoname=vancouver&output=KML
csv (Comma Separated Values)
http://geonames.nrcan.gc.ca/api?geoname=vancouver&output=csv
csv2 (Pipe Separated Values)
http://geonames.nrcan.gc.ca/api?geoname=vancouver&output=csv2
tab (TAB Separated Values)
http://geonames.nrcan.gc.ca/api?geoname=vancouver&output=tab
RSS (Really Simple Syndication, Web feed Format)
http://geonames.nrcan.gc.ca/api?geoname=vancouver&output=RSS
ATOM (Atom Syndication Format, XML for Web feed)
http://geonames.nrcan.gc.ca/api?geoname=vancouver&output=ATOM
application/json (JavaScript Object Notation)
http://geonames.nrcan.gc.ca/api?geoname=vancouver&output=application/json
2- Searching Feature Name (Geoname), and using the wildcard (%25)
The Feature Name is defined here.
http://geonames.nrcan.gc.ca/api?geoname=toronto&output=html&match=exact
http://geonames.nrcan.gc.ca/api?geoname=toron&output=html&match=leading
is the same as
http://geonames.nrcan.gc.ca/api?geoname=toron&output=html
geoname = [minimum of 2 characters]
match = exact or leading (default)
You may add a parameter called "match" in the URI with either a value of "exact" or "leading". Leading puts a wildcard at the end (not at the beginning) of the parameter "geoname" for the search. The wildcard is %25 (it is the character % written in hexadecimal), for example:
http://geonames.nrcan.gc.ca/api?geoname=%25white%25mount&output=html
3- Searching by CGNDB Key
The CGNDB key is defined here.
http://geonames.nrcan.gc.ca/api?cgndbKey=BADHP&output=html
http://geonames.nrcan.gc.ca/api?cgndbKey=BADHP&output=csv
http://geonames.nrcan.gc.ca/api?cgndbKey=BADHP&output=xml
http://geonames.nrcan.gc.ca/api?cgndbKey=BADHP&output=GML3
http://geonames.nrcan.gc.ca/api?cgndbKey=BADHP&output=ATOM
cgndbKey = [5 characters]
The cgndbKey parameter can only be combined with parameters defining the output and the language of the results. The use of the wildcard %25 is legal in the cgndKey sequence.
4- Searching by Feature Id
The Feature Id is explained here.
http://geonames.nrcan.gc.ca/api?featureId=4d00fe4cba2011d892e2080020a0f4c9&output=html &language=en
featureId = [32 characters]
The featureId parameter can't be combined with any other search parameter.
5- Searching by Dates
http://geonames.nrcan.gc.ca/api?conciseCode=CITY®ionCode=35&dateSince=1990-02-01&output=html
dateSince = YYYY-MM-DD
6- Searching by Circular Area
http://geonames.nrcan.gc.ca/api?circle=54,-120,20&conciseCode=LAKE&output=html
circle = latitude of centre in decimal degrees, longitude of centre (negative for longitudes in the North American system) in decimal degrees, and radius of search area in kilometres.
7- Searching by Concise Code (Feature Type)
The Concise Code, usually called the Feature Type, is defined here.
http://geonames.nrcan.gc.ca/api?regionCode=35&conciseCode=CITY,TOWN&output=html
conciseCode = [1-4 characters],[1-4 characters],etc.
Many concise codes may be entered. For example to get all city, town, municipalities, set:
ConciseCode=CITY,TOWN,VILG,HAM, UNP,MUN1,MUN2,DMUN
ConciseCode=F (for Natural Features) is equivalent to
ConciseCode=BAY,BCH,CAPE,CAVE,CHAN, CLF,CRAT,FALL,ISL,MTN, PLN,RAP,RIVF,SHL,SPRG, VALL,VEGL,GLAC, SEA,SEAF,SEAU,LAKE,RIV
ConciseCode=P (for Places) is equivalent to
ConciseCode=AIR,CAMP,CITY,FOR,GEOG, HYDR,IR,MAR,MIL,MISC, MUN1,MUN2,PARK,PROV, RECR,RES,ROAD,SITE, TOWN,UNP,VILG,DMUN,HAM, RAIL,TERR
ConciseCode=H (for Hydrographic Features) is equivalent to
ConciseCode=BAY,CHAN,FALL,RIVF,SHL,SPRG, SEA,SEAF,SEAU,LAKE,RIV
Here are the Concise codes (also called the Feature Type, and Feature Categories):
| Concise Codes | |
|---|---|
| Code | Feature |
| CITY | City |
| TOWN | Town |
| VILG | Village |
| HAM | Hamlet |
| UNP | Unincorporated area |
| IR | Indian Reserve |
| GEOG | Geographical area |
| PARK | Conservation area |
| MIL | Military area |
| PROV | Province |
| TERR | Territory |
| MUN1 | Other municipal/district area - major agglomeration |
| MUN2 | Other municipal/district area - miscellaneous |
| More Concise Codes | |
| Code | Feature |
| AIR | Air navigation feature |
| BAY | Bay |
| BCH | Beach |
| CAMP | Miscellaneous campsite |
| CAPE | Cape |
| CAVE | Cave |
| CHAN | Channel |
| CLF | Cliff |
| CRAT | Crater |
| DMUN | District municipality |
| FALL | Falls |
| FOR | Forest |
| GLAC | Glacier |
| HYDR | Hydraulic construction |
| ISL | Island |
| LAKE | Lake |
| MAR | Marine navigation feature |
| MISC | Miscellaneous |
| MTN | Mountain |
| PLN | Plain |
| RAIL | Railway feature |
| RAP | Rapids |
| RECR | Recreational site |
| RES | Natural resources site |
| RIV | River |
| RIVF | River feature |
| ROAD | Road feature |
| SEA | Sea |
| SEAF | Sea feature |
| SEAU | Undersea feature |
| SHL | Shoal |
| SITE | Miscellaneous site |
| SPRG | Spring |
| VALL | Valley |
| VEGL | Low vegetation |
8- Searching by Region Code - Downloading the whole database
Note: The regionCode parameter should be combined with other parameters, for example, with the geoname parameter, to constrain the search to names located in a specific region:
http://geonames.nrcan.gc.ca/api?geoname=Charlot®ionCode=11
http://geonames.nrcan.gc.ca/api?geoname=Charlot®ionCode=11,47
regionCode = [2 digits],[2 digits],etc.
| Region Codes | |
|---|---|
| Code | Region |
| 10 | Newfoundland and Labrador |
| 11 | Prince Edward Island |
| 12 | Nova Scotia |
| 13 | New Brunswick |
| 24 | Quebec |
| 35 | Ontario |
| 46 | Manitoba |
| 47 | Saskatchewan |
| 48 | Alberta |
| 59 | British Columbia |
| 60 | Yukon |
| 61 | Northwest Territories |
| 62 | Nunavut |
CAUTION: Requesting a full region is a long request, and will take many minutes to complete.
IMPORTANT : Downloading the entire database or large datasets through the API is unnecessary since the data is available in files that are updated weekly, and are easily downloadable from http://geobase.ca as described in our Digital Data section in the left menu above.
There are about 350,000 names in the database, and there is a limit to the number of records returned by one query. Currently the limit has been set to 10,000 records on one query. To download the whole database, one would require some 41 bounding box queries. Here is an example:
http://geonames.nrcan.gc.ca/api?bbox=45.0,-70.0:47.0,-60.0®ionCode=13
One would have to query by combining the region and Bounding Box parameters (explained below) to divide a region into small requests. Some regions have more than 10,000 records and thus require more queries:
QC = regionCode = 24 requires 12 queries,
ON = regionCode = 35 requires 6 queries,
BC = regionCode = 59 requires 5 queries,
NL = regionCode = 10 requires 3 queries,
NS = regionCode = 12 requires 3 queries,
NB = regionCode = 13 requires 2 queries,
MB = regionCode = 46 requires 2 queries,
SK = regionCode = 47 requires 2 queries,
regionCode = 11, 48, 60, 61, 62 and 73 require 1 query.
If you encounter a space-memory problem, the same result may be obtained using the WFS service. Using the WFS service, you may query for fewer columns.
9- Searching by rectangular region (Bounding Box - BBOX)
The bbox parameter is useful to constrain the search to names within a rectangular area.
The bbox parameter is a rectangular geographic region defined between latitudes and longitudes in decimal degree format. The coordinates of bottom left and top right corners are separated by a colon (:), for example: bbox=40.1,-81.1:41.1,-80.1 In other words, it is defined with min y (latitude), min x (longitude), max y (latitude), max x(longitude).
http://geonames.nrcan.gc.ca/api?bbox=43.7,-79.4:43.8,-79.35&output=html
http://geonames.nrcan.gc.ca/api?bbox=43.7,-79.4:43.8,-79.35&output=GML3
10- Searching by Status Code
The possible statuses of a name are briefly explained here.
http://geonames.nrcan.gc.ca/api?statusCode=A®ionCode=11&conciseCode=VILG
statusCode = [1-3 charcaters],[1-3 characters],etc.
Note : The API returns a field called status_term = Official, Rescinded or Withdrawn. To get the API to return only the Official names, set the statusCode to A:
statusCode=A is equivalent to
statusCode=A1,A2,A3,A4,A5,A6,A7,A8,A10,A11,A12, A13,M1,P1,Q1,S1,U1,U2,U3,W1
The other statuses are listed in the table of API parameters.
11- Searching by NTS Map Number
The NTS map number is explained here.
http://geonames.nrcan.gc.ca/api?ntsMap=011L03
or
http://geonames.nrcan.gc.ca/api?ntsMap=C.4405
ntsMap = [NTS no of 6 characters, 999A99] or [Can. hydrographic chart no, C.9999]
12- Restricting the results to French when available
http://geonames.nrcan.gc.ca/api?language=fr&geoname=48ROAD&output=html
http://geonames.nrcan.gc.ca/api?language=fr&geoname=MONTREAL&output=html
http://geonames.nrcan.gc.ca/api?language=fr&geoname=S%25JOHN%25&output=html
http://geonames.nrcan.gc.ca/api?language=fr&geoname=MANIW&output=html
language = en or fr
13 - Example of results in XML format
- <?xml version="1.0" encoding="ISO-8859-1"?>
- <SearchResults xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <PlaceName>
<geoname>Charlottetown</geoname>
<status_term>Official</status_term>
<latitude>46° 15' North</latitude>
<longitude>63° 8' West</longitude>
<latdec>46.2500000</latdec>
<londec>-63.1332999</londec>
<coord_acc_m>2000</coord_acc_m>
<concise_term>Geographical area</concise_term>
<generic_term>Royalty</generic_term>
<region_name>Prince Edward Island</region_name>
<location>Queens</location>
<nts_map>011L03,011L06</nts_map>
<datum>NAD27</datum>
<cgndb_key>BAETC</cgndb_key>
<feature_id>0c0b95ab849c20c3ad1819042edaf7ec</feature_id>
</PlaceName>