|
|
 |
Canadian Geographical Names
Natural Resources Canada |
This documents intended audience is for application developers using the GNSS API
as a web service. This documents covers:
A User’s Guide is now available (as of 2 November 2005).
It describes the access to the API
and shows many examples of its usage and options. The WFS Web Service, similar to the API,
is another method to receive automatic responses from the CGNS. The WFS
follows international standards developed by the Open Geospatial Consortium.
WFS access is also described in the GNSS User’s Guide. The API was created to
simplify the access to the WFS, to validate the requests, to return informative error messages, and
to provide a simple way to get automatic answers for complex requests of geographical names.
GNSS User’s Guide (version 1.1) [PDF]
|
|
Parameter Name
|
Rule
|
Default
|
Example
|
|
geoname
|
Exclusion rule applies.
Maximum length is 100 characters.
Minimum length is two characters.
|
none
|
Montreal
Saint John
|
|
cgndbKey
|
Exclusion rule applies.
Fixed length of 5 characters, all alphabetic, upper case.
|
none
|
AAAAA
FGFDC
|
|
featureId
|
Exclusion rule applies.
Maximum 10 digits.
|
none
|
1234567890
|
|
dateSince
|
YYYY-MM-DD
|
none
|
2003-01-23
|
|
bbox
|
Exclusion rule applies.
min-x,min-y:max-x,max-y
|
none
|
-142.0,0.0:-52.0,84.0
|
|
circle
|
Exclusion rule applies.
x, y, radius,
Radius represents a measurement in kilometers.
|
none
|
-142.0,0.0, 5
|
|
regionCode
|
2 digit number.
Comma separated list.
|
If no regionCode is provided, all are searched.
|
10
11
|
|
conciseCode
|
Maximum size is 10 characters.
Comma separated list.
|
If no conciseCode is provided, all are searched.
|
UPN
CITY
|
|
match
|
exact
leading
|
exact
|
exact
leading
|
|
output
|
xml
html
csv
|
xml
|
csv
|
|
datum
|
EPSG:4267
|
EPSG:4267
|
EPSG:4267
|
|
ntsMap
|
Maximum one map
|
none
|
031G05
C.4405
|
|
language
|
en or fr
|
en
|
en
|
|
order
|
geoname, regionCode or conciseCode
|
geoname
|
geoname
|
Example:
http://gnss.nrcan.gc.ca/gnss-srt/api?regionCode=24&geoname=Montreal
|
|
Error Code
|
Translation
|
|
1000
|
The request had insufficient data.
|
|
1001
|
The Post to WFS failed.
|
|
1002
|
Connection to WFS was not established.
|
|
1003
|
Failed to receive proper response from WFS.
|
|
1004
|
Failed to parse response from WFS.
|
|
1005
|
Max Allowed Results Reached.
|
|
2000
|
Invalid number of coordinates in bbox parameter
|
|
2001
|
The bbox or circle coordinate is not a valid number
|
|
2002
|
Longitude value must be from -180 to 180 degrees
|
|
2003
|
Latitude value must be from -90 to 90 degrees
|
|
2004
|
Maximum latitude or longitude vlaue must be greater than the corresponding minimum value
|
|
2005
|
Invalid number of coordinates in circle parameter
|
|
2006
|
Invalid radius value, must be greater then 0 km
|
|
2010
|
Invalid date format in dateSince parameter.
Format is dd-mm-yyyy (08-24-1967)
|
|
2015
|
Invalid datum value supplied
|
|
2020
|
One of the feature values provided is invalid
|
|
2025
|
Invalid language value provided
|
|
2030
|
Invalid number of characters for the geoname,
must be greater than 2 and less than 100 characters in length
|
|
2035
|
Invalid match value provided
|
|
2040
|
Invalid order value provided
|
|
2045
|
Invalid output value provided
|
|
2050
|
The refer value is not a valid URL
|
|
2055
|
One of region values provided is invalid
|
|
2060
|
Invalid cgndbKey value. Must be composed of alphabetic characters only.
|
|
2210
|
Must include at least one of bbox, circle, featureId, key, dateSince,
or geoname parameter in the request
|
|
2220
|
Cannot specify any of bbox, circle, dateSince, feature, featureId,
match, geoname, ntsMap or region parameters when the key parameter is used
|
|
2230
|
Cannot specify any of bbox, circle, dateSince, feature, key, match,
geoname, ntsMap or region parameters when the featureId parameter is used
|
|
2240
|
Cannot specify a bbox and a circle parameter in the same request
|
|
2250
|
Cannot specify a match parameter when a geoname parameter is not provided
|
|
2300
|
Invalid parameter in HTTP request
|
|
Code
|
Term
|
|
CITY
|
City
|
|
TOWN
|
Town
|
|
VILG
|
Village
|
|
HAM
|
Hamlet
|
|
UNP
|
Unincorporated area
|
|
MUN1
|
Major municipal/district area - major agglomeration
|
|
MUN2
|
Other municipal/district area - miscellaneous
|
|
DMUN
|
District municipality
|
|
IR
|
Indian Reserve
|
|
GEOG
|
Geographical area
|
|
PARK
|
Conservation area
|
|
MIL
|
Military area
|
|
RIV
|
River
|
|
LAKE
|
Lake
|
|
SPRG
|
Spring
|
|
CHAN
|
Channel
|
|
FALL
|
Falls
|
|
RAP
|
Rapids
|
|
RIVF
|
River feature
|
|
BAY
|
Bay
|
|
CAPE
|
Cape
|
|
BCH
|
Beach
|
|
SHL
|
Shoal
|
|
ISL
|
Island
|
|
MTN
|
Mountain
|
|
VALL
|
Valley
|
|
PLN
|
Plain
|
|
GLAC
|
Glacier
|
|
CRAT
|
Crater
|
|
CLF
|
Cliff
|
|
CAVE
|
Cave
|
|
FOR
|
Forest
|
|
VEGL
|
Low vegetation
|
|
SEA
|
Sea
|
|
SEAF
|
Sea feature
|
|
SEAU
|
Undersea feature
|
|
RAIL
|
Railway feature
|
|
ROAD
|
Road feature
|
|
AIR
|
Air navigation feature
|
|
MAR
|
Marine navigation feature
|
|
HYDR
|
Hydraulic construction
|
|
RECR
|
Recreational site
|
|
CAMP
|
Miscellaneous campsite
|
|
RES
|
Natural resources site
|
|
SITE
|
Miscellaneous site
|
|
MISC
|
Miscellaneous
|
|
PROV
|
Province
|
|
TERR
|
Territory
|
|
Code
|
Translation
|
|
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
|
The GNSS application has the ability to allow application developers to seemlessly
incorporate GNSS services into their own application.
Other applications can redirect users to the GNSS application, while not leaving the flow of their own application,
by use of parameters:
The refer key, which will contain the http url of the calling application. Example:
http://gnss-nrcan.gc.ca/gnss-srt/referHandler.jsp?refer=http://www.mydomain.com/myapplication
Using the GNSS application in this manner allows a user to use to the GNSS search
page, perform a search, select a GEONAME from the search results returned in the results page, and then click the OK button.
What does this do? On the special case that someone has entered the GNSS application
with a refer value, an OK button is displayed. Once the user has selected an item
from the list of return items, the GNSS application redirects the user back to the original
application, and includes in the url ( QUERY STRING ), the latitude, longitude, and geoname
selected. These values are available to the calling application by way of the query string.
An optional Language value can be use in conjunction with the refer. Including the
language parameter will enable the pages to be displayed in the language specified, either English or French.
If the language is unspecified, the default language is English.
For English services:
http://gnss.nrcan.gc.ca/gnss-srt/referHandler.jsp?refer=http://www.mydomain.com/myapplication&language=en
For French services:
http://gnss.nrcan.gc.ca/gnss-srt/referHandler.jsp?refer=http://www.mydomain.com/myapplication&language=fr
An example explaining how the Refer application works and may be implemented into your applications is given at: http://gnss.nrcan.gc.ca/gnss-srt/referExample.html.
There are optional keys that can be used for the refer component.
-
conciseCode can contain comma separated values specified in the Concise Code table.
-
regionCode can contain comma separated values specified in the Region Code table.
-
geoname can contain the complete or partial name of the place name you are searching for.
-
match If a geoname is specified, this determines if there is a leading edge or exact search.
|
|
If you are using cgndbKey or featureId, then
geoname, bbox, circle cannot be used.
|
|
