Acknowledgements

- Geographical Names Section, Centre for Topographic Information

- GeoAccess Division, Canada Centre for Remote Sensing

Introduction

The CGDI Gazetteer Service will provide a web service, which returns geometries for known placenames. This service sits atop various Web Feature Services (WFS). The WFS contains all feature data and geometries. The purpose of this service is to provide a simple interface/wrapper for those wishing gazetteer services.

The CGDI Gazetteer Service extends traditional gazetteer services with the following functionality:

- Returning complex geometries (polygons, lines) for features which are linked between the toponymic name source and feature geometry collections

- Returning calculated bounding box / area of interest geometry for features which are linked between the toponymic name source and feature geometry collections

- Combining placenames with spatial searches

- Discovering placename information via textual or spatial search

The Service provides geometries for placenames as per the concise gazetteer as obtained from CTIO. The Service also provides complex geometries as per Atlas 1M data, for tagged features.

The Service utilizes the WFS specification to interrogate both the name source and feature data to perform on the fly 'joins' of features to toponymic records.

The Service returns record(s) for matching placenames with geometry, encoded in GML2.1, and also provides a URL for full WFS query of the feature within its native schema, via XLink. The Service also supports complex queries, such as constraining by province, entity type, as well as spatial region of interest. A client, if aware, can also query the Service by CGNDB unique key to derive a result.

The Service does not provide intelligence for generics or abbreviations. It is expected that client clients take this into account before building entry points to the service.

Below is a diagram of how the service derives feature geometry for toponymic data. The CGDI Gazetteer Service performs ‘on the fly’ linking of toponymy to feature data.

Gazetteer Data Sources

Concise Gazetteer of Canada – digital version

This data, compiled for a paper copy gazetteer published in 1997, includes a selection of the official names for all of Canada. About 47,000 names are included. The following information is provided: Place/feature name; Entity type; Province or territory; Location; NTS (National Topographic System) Map or Hydrographic Chart; Latitude and Longitude. Names were selected based on both objective and subjective criteria. Incorporated and unincorporated populated places, National Parks, Indian Reserves and pan-Canadian names are included systematically, together with all physical features on 1:2 million scale maps. A selection of features is also included from other, larger map scales, as well as undersea features and names significant for historical, cultural or other reasons.

Feature Data Sources

Geometry made available through the Gazetteer Service is from the CGDI national resolution framework. This framework consists of a set of fully integrated data at a nominal scale of 1:1,000,000, and is accurate to approximately 1 km. Much of the data was either derived from or aligned to the Canadian portion of the VMAP level 0 data set (originally DCW) as adjusted and distributed by The National Atlas of Canada. The framework currently consists of the following themes: hydrography, administrative boundaries and railroads. It is available at no cost on the GeoGratis Web site http://geogratis.cgdi.gc.ca (See National Frameworks link under the Data Download heading).

HTTP Request Rules

The CGDI Gazetteer Service accepts both HTTP GET and HTTP POST. Keyword parameters may be entered in either case, however value parameters are case sensitive.

CGDI Gazetteer Service Operations

The Service supports two (2) operations

- GetCapabilities

- GetPlacenameGeometry

GetCapabilities

The purpose of the GetCapabilities operation is to provide general information about the service itself and specific information about the name sources used.

Request parameter	Required/Optional	Description
VERSION=version	R	Request version
REQUEST=GetCapabilities	R	Request name

See Appendix A for example GetCapabilities requests and responses.

GetPlacenameGeometry

The purpose of the GetPlacenameGeometry operation is to return the geometries for a placename inputted by a request.

Request Parameter	Required/Optional	Description
VERSION=version	R	Request version
REQUEST=GetPlacenameGeometry	R	Request name
PLACENAME=placename	O	Placename. Required for non-key or bbox type queries
ENTITYTYPES=entity_type_list	O	Comma separated list of entity type codes. If not used all entity types are searched. See Appendix B for entity type codes
PROVTERR=province_territory_list	O	Comma separated list of province / territory codes. If not used all provinces and territories are searched. See Appendix B for province and territory codes
KEY=cgndb_id	O	Searches CGNDB Key; usage of this parameter voids all other parameters
GEOMTYPE=simple\|complex\|bbox	O	Simple will return points; complex will return complex geometries (polygon, line) for supported features; bbox will return the minimum bounding rectangle for supported features.
WILDCARDS=true\|false	O	Whether wildcards should be used
FORMAT=output_format	O	Default XML
BBOX=minx,miny,maxx,maxy	O	For spatial searching; required for non key or placename type queries

See Appendix A for example GetPlacenameGeometry requests and responses.

The CGDI Gazetteer Service is available at:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi

An online sample interface to the CGDI Gazetteer is available at:

http://cgdi-dev.geoconnections.org/prototypes/cgdigaz/sample.htm

Issues:

- provinces: if we want to include this as a constraint, what is the best way to accept this (as two character codes [e.g. ON], as numerical codes [e.g. 04]

- same with entity_types: how do we handle these: English, French, both?

Appendix A: Example Requests and Responses

GetCapabilities

Request:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetCapabilities&

GetPlacenameGeometry

Search for placename ‘Toronto’:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetPlacenameGeometry&placename=Toronto&

Search for placename ‘Toronto’ within a spatial area of interest:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetPlacenameGeometry&placename=Toronto&bbox=-90,40,-70,50&

Search for all placenames within a given geographical area of interest:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetPlacenameGeometry&bbox=-79.47338,43.611822000000004,-79.38641,43.67484&

Search for placename like ‘Toronto’:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetPlacenameGeometry&placename=Toronto&wildcards=true&

Search for placename like ‘Toronto’ constrain by province / territory codes:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetPlacenameGeometry&placename=Toronto&provterr=35&

Search for placename ‘Toronto’ and constrain by entity type codes:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetPlacenameGeometry&placename=Toronto&entitytypes=UNP/LNO&

Search for placename ‘Toronto’ and return complex geometry for supported / linked records:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetPlacenameGeometry&placename=Toronto&geomtype=complex&

Search for placename ‘Toronto’ and return bounding box geometry for supported / linked records:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetPlacenameGeometry&placename=Toronto&geomtype=bbox&

Search for CGNDB key ‘FCWYG’ and return complex geometry for supported / linked records:

http://cgdi-dev.geoconnections.org/cgi-bin/prototypes/cgdigaz/cgdigaz.cgi?version=1.0&request=GetPlacenameGeometry&key=FCWYG&geomtype=complex&

Keyword Value Pair rules

All keyword value pairs can be used in combination with one another. All GetPlacenameGeometry requests MUST provide either a ‘placename’ or ‘key’ keyword and accompanying value.

Appendix B: Code Mappings

Please see ISO document (Approach to Development of the New ISO/IEC 18038 Identification and Mapping of Various Categories of Jurisdictional Domains) for more information on province / territory codes.

http://www.jtc1sc32.org/sc32/jtc1sc32.nsf/Attachments/DDA8599970A805DA8525696C0041C1AE/$FILE/32N0535.PDF

Province / Territory Codes

Code	Province/Territory
48	Alberta
59	British Columbia
46	Manitoba
13	New Brunswick
10	Newfoundland
61	Northwest Territories
12	Nova Scotia
62	Nunavut
35	Ontario
11	Prince Edward Island
24	Quebec
47	Saskatchewan
60	Yukon

Entity Type Codes

Code	Entity Type
ITY/VIL1	City
OWN/VIL2	Town
VILG/VILG	Village
HAM/HAM	Hamlet
MUN1/AZM1	Other municipal/district area - maj. aggl.
MUN2/AZM2	Other municipal/district area - misc.
UNP/LNO	Unincorporated area
IR/RI	Indian Reserve
EOG/GÉOG	Geographical area
PARK/PARC	Conservation area
MIL/MIL	Military area
IV/CDE	River
IVF/EFLV	River feature
ALL/CHUT	Falls
AKE/LAC	Lake
SEA/MER	Sea
SEAU/SMER	Undersea feature
HAN/CHEN	Channel
AP/RAP	Rapids
BAY/BAEI	Bay
APE/CAP	Cape
BCH/PLAG	Beach
SHL/H-FD	Shoal
ISL/ÎLE	Island
LF/ESC	Cliff
MTN/MNT	Mountain
VALL/VALL	Valley
PLN/PLNE	Plain
AVE/CAV	Cave
RAT/CRAT	Crater
LAC/GLAC	Glacier
VEGL/VÉGB	Low vegetation
MISC/DIV	Miscellaneous
PROV/PROV	Province
ERR/TERR	Territory

* Note: these are expected to change to numeric code values in forthcoming modifications.