GIN DT-12-001

Groundwater Information Network Groundwater Geoscience program Earth Sciences Sector / Natural Resources Canada Geological Survey of Canada

GIN General Gazetteer API

Date: July 22, 2015 Document Reference Number: GIN DT-12-001 Category: Technical Documentation Author: Eric Boisvert, Heryk Julien

1

GIN DT-12-001

Revision history Date

Release

Author

Description

2012-09-25

Draft

Eric Boisvert

First draft for comments

2012-09-27

Revision

Eric Boisvert

2012-09-28

2013-03-05

2013-08-29

Addition

Revision and updates

Revisions and updates for new features

Eric Boisvert

Héryk Julien

Héryk Julien



Added specific example for DLS



Edits to the text in general (more info)



Fixed typo (gazeteer -> gazetteer) throughout document



Added information for other provinces (BC and Ontario)



Added Schema (annex 1)



Validated and updated examples and links



Corrected typos



Added annex 2



General editing



Added JSON and JSONP service formats



Added section on 3G web client

2013-12-16

Fixed compatibility issue

Héryk Julien



Compatible with IE8 and following versions

2014-03-24

Change form examples (added and class

Eric Boisvert



Form snippets now have labels wrapped in



Minor cosmetic changes

2014-07-09

Added documentation on autolaunch attribute for Gin General Client

Eric Boisvert



Added a new behavior (autolaunch) to the client

2014-07-17

Change service URL

Eric Boisvert



Changes ngwdbdnes.cits.nrcan.gc.ca to gin.gw-info.net

2

GIN DT-12-001

Table of content 1. GIN General Gazetteer API 2. Use case: Service Interactions 3. GIN General Gazetteer Client Application Annex 1. XSD schema of Gazetteer API query operation results Annex 2. Gazetteer API request examples

3

GIN DT-12-001

1. GIN General Gazetteer API 1.1 Introduction This document describes the GIN General Gazetteer API (3G). The 3G is common interface proxy for heterogeneous gazetteers implemented by several governmental and nongovernmental organisations. API provides a simpler interface to the heavy machinery of WFS-G (OGC 05-035r2, OGC 11-122r1) and CSW (07-006r1). WFS-G requires the client to handle XSD parsing to discover the schema and OGC Filter request to extract data. On the flip side, WFS-G provides a more sophisticated filtering. Also, since 3G is a wrapper over a series of heterogeneous gazetteers of which very few supports WFS-G style filters, let alone a common result format, this API proposes minimalistic approach that is suitable for simple use cases. The API supports four operations: List, Form, Describe and the Query call itself The 3G supports variable query parameters and is operational in French (fr) and English (en).

1.2 Online documentation Trac: http://s-stf-gin.nrn.nrcan.gc.ca:8000/trac/wiki/NgwdGazetteerService (internal) Service base URL (): http://.../ngwds//gazetteer/ * * Language = “fr” for French or “en” for English.

Eg: http://gin.gw-info.net/service/ngwds/en/gazetteer/

1.3 Operations The operation on the gazetteer follows this sequence: 1. The client invokes the List operation to get a collection of gazetteers and their IDs. From this list, the client can either display the list to the user and let him choose one instance or directly pick a known gazetteer to extract the form at step #2. 2. The client invokes Form with the ID of the gazetteer gained from step #1 to get a HTML form. This form can be used as-is or parsed by the client to create its own form. The elements of this form are the parameters required by the query operation. Each HTML Form element having a name attribute. 3. Optionally, the client can get the form documentation with the Describe operation and display it to the user. 4. The client invokes the Gazetteer with the Query operation using the parameters provided by operation in #2.

4

GIN DT-12-001 1.3.1 List This operation returns a list of gazetteers supported by the service. In a user interface, this step is normally used to populate a control where a user can pick a specific gazetteer. custom Primary Forms Screen1



Figure 1: Combo box to be filled with a list of gazetteers Invocation: list.xml Eg: 



http://gin.gw-info.net/service/ngwds/en/gazetteer/list.xml (English) http://gin.gw-info.net/service/ngwds/fr/gazetteer/list.xml (French)

Result (eg): Extent of canadian provinces and territories Search for a canadian place or feature Search for an address or postal code Search for a well by identifier Zoom to monitoring station Extent of an NTS map sheet Division of land of Ontario (township, concession and lot) Division of land of British Columbia Western Canada Dominion Land Survey

Formats: A format suffix must be added at the end of the method URL. The three formats supported so far are xml, json and jsonp.   

http://gin.gw-info.net/service/ngwds/en/gazetteer/list.xml http://gin.gw-info.net/service/ngwds/en/gazetteer/list.json http://gin.gw-info.net/service/ngwds/en/gazetteer/list.jsonp (with or without “callback” parameter. Eg: “?callback=myCallbackFunction”)

5

GIN DT-12-001

By default all gazetteer services are listed with their unique ID. However subsets of gazetteer services may be generated by adding a “list” parameter to the URL. For the moment two predefined subsets of services are available named “gin” and “troo”. This feature is used to organise gazetteers into convenient collections for specific purposes. Eg:  

http://gin.gw-info.net/service/ngwds/en/gazetteer/list.xml?list=troo http://gin.gw-info.net/service/ngwds/en/gazetteer/list.xml?list=gin

It is also possible to pass a custom collection of services by proving an array of service IDs. IMPORTANT: Use single and note double quotes in the ID array. Eg: 

http://gin.gw-info.net/service/ngwds/en/gazetteer/list.xml?list=['wellid','province','nts']

1.3.2 Form Each mediated gazetteer has different set of query parameters such as restricted sets of mandatory keywords. To avoid creating a special format to convey this information, the current operation simply returns the list of required parameters as an HTML form. HTML form encodes well know form elements such as free text box, pick list (HTML select), etc. The form can be used as-is in a web page or parsed to extract the controls and create a local representation. Invocation: form/. Eg: http://gin.gw-info.net/service/ngwds/en/gazetteer/form/dls.html Result (eg): Section
Township
Range
Meridian

Labels are wrapped in HTML span elements and assigned a CSS class to facilitate styling and extraction.

6

GIN DT-12-001

Figure 2: Form provided by the service

Formats: A format suffix must be added at the end of the form method url. The four formats supported so far are html, xml, json and jsonp. All formats contain an html snippet for represent the form.    

http://gin.gw-info.net/service/ngwds/en/gazetteer/form/dls.html http://gin.gw-info.net/service/ngwds/en/gazetteer/form/dls.xml http://gin.gw-info.net/service/ngwds/en/gazetteer/form/dls.json http://gin.gw-info.net/service/ngwds/en/gazetteer/form/dls.jsonp (with or without “callback” parameter. Eg: “?callback=myCallbackFunction”)

1.3.3 Describe The Describe operation provides a small HTML snippet that can be displayed to the user. It can be used to display instructions and examples to facilitate data entry. Invocation: describe/. Eg: http://gin.gw-info.net/service/ngwds/en/gazetteer/describe/dls.html Result (eg): Exemple : Section : 12, Township : 023, Range : 10, Meridian W4
Note: Some fields may be left blank

Formats: A format suffix must be added at the end of the form method url. The four formats supported so far are html, xml, json and jsonp. All formats contain html snippets for displaying forms.  

http://gin.gw-info.net/service/ngwds/en/gazetteer/describe/dls.html http://gin.gw-info.net/service/ngwds/en/gazetteer/describe/dls.xml

7

GIN DT-12-001  

http://gin.gw-info.net/service/ngwds/en/gazetteer/describe/dls.json http://gin.gw-info.net/service/ngwds/en/gazetteer/describe/dls.jsonp (with or without “callback” parameter. Eg: “?callback=myCallbackFunction”)

1.3.4 Query Each gazetteer requires a different set of parameters, provided by the Form operation. Those parameters must be used to query the gazetteer. The gazetteer query return geometries (bounding box and/or point localisation) corresponding to the submitted form data. Invocation: query/. Data is sent in GET (eg: ?=&=…) The gazetteer will always return a document of the same structure (see annex 1). Keep in mind that while g:centroid is always present, g:boundedBy is present only if available. Also note that in EPGS:4326, axis order is y,x.

8

GIN DT-12-001 Eg: XML 12-023-10-W4 50.94294357299805 -111.272430419922 50.9356117248535 -111.284034729004 50.9502754211426 -111.26082611084

JSON {"gazetteer": [ { "id":"12-023-10-W4", "name":"12-023-10-W4", "centroid": {"type":"Point","coordinates":[50.94294357299805,-111.272430419922], "locationtype":"estimated"} , "boundedby": {"type":"Envelope","coordinates":[[50.9356117248535,-111.284034729004],[50.9502754211426,111.26082611084]],"locationtype":""} } ]}

Formats: A format suffix must be added at the end of the method url. Three formats are currently supported so far, xml, json and jsonp. 





http://gin.gwinfo.net/service/ngwds/en/gazetteer/query/dls.xml?section=12&township=023&range=10&meridian=W 4 http://gin.gwinfo.net/service/ngwds/en/gazetteer/query/dls.json?section=12&township=023&range=10&meridian= W4 http://gin.gwinfo.net/service/ngwds/en/gazetteer/query/dls.jsonp?section=12&township=023&range=10&meridian= W4 (with or without “callback” parameter. Eg: “?callback=myCallbackFunction”)

9

GIN DT-12-001

2. Use Case: Interaction with the service The following section is for web developers who wish to build their own client to interact with the 3G API. 2.1 Cross-domain / Single Origin Poliy (SOP) It is important to understand that, as any web services that can be invoked from a web browser application, extra steps must be taken to handle SOP (Single Origin Policy). The general method to deal with this is to implement a server side proxy that will handle the transaction with the remote service on behalf of the client application. For more details on SOP and technologies to handle it, see http://en.wikipedia.org/wiki/Same_origin_policy

An alternative to installing a server side proxy is the use of the JSONP. All 3G API operations responses such as List, Form, Describe and Query can formatted in JSONP. Note that a “callback” parameter naming your callback function can be added to 3G JSONP URLs (Eg: “?callback=myCallbackFunction”). For more details on JSONP, see http://en.wikipedia.org/wiki/JSONP Whichever the chosen approach, it is worthwhile to note that the use of JQuery can ease Javascript, Ajax and JSONP programming and significantly leverage web browser client development. For more details on JQUERY, see http://en.wikipedia.org/wiki/Jquery 2.2 Example session with DLS (Dominion Land Survey) This section provides a specific example with DLS (Dominion Land Survey) that covers Canadian Prairie Provinces. The normal flow of operations is  Get the list of gazetteers (only once)  When a gazetteer is selected, get the corresponding form from the service  Optionally, to provide more information for the client, invoke the describe operation  When the form is filled, extract the parameters names and values and send them to the service  Parse the query result For a fully flexible application, all four operations shall be used. However, it is possible to skip the first three operations and only use the direct invocation of the gazetteer if the parameters and the service end point are already known. It is normally not recommended because the parameter list can change. 2.2.1 Getting the list of available Gazetteers Client invokes the List operation to get a list of gazetteers. This operation might not be necessary if the gazetteer id is already known, but this step can be used nonetheless to check 10

GIN DT-12-001 if the expected gazetteer is still available. This operation is generally done only once at the initialisation of the application and cached on the client side. Invocation: list.xml Eg: http://gin.gw-info.net/service/ngwds/en/gazetteer/list.xml The service returns a list similar to this one: Search for a canadian place or feature Search for an address or postal code Search for a well by identifier Extent of an NTS map sheet Division of land of Ontario (township, concession and lot) Division of land of British Columbia Western Canada Dominion Land Survey Extent of canadian provinces et territories

(DLS highlighted in grey)

2.2.2 Requesting a specific gazetteer form Each gazetteer has different parameters, but always has the same result format. The list of parameters is provided as an HTML form that can be included directly into the web page or parsed to create a client specific form (eg, in Silverlight). This design allows changes in the gazetteer parameters without affecting client applications (that should automatically adapt). However, the developer can hardcode the form if the he/she is confident that the parameters won't change or is ready to make the change to the code when such changes happen. To get the form, the client application must invoke the form operation with the "dls" id (taken from the list in the previous operation, see grayed out section) Invocation: form/. Eg: http://gin.gw-info.net/service/ngwds/en/gazetteer/form/dls.html Result (eg): Section
Township
Range
Meridian

11

GIN DT-12-001

The client application uses this information to build a form (or use a hardcoded version). 2.2.3 Querying a gazetteer service Each gazetteer is queried by accessing a standard URL structure. The gazetteer specific parameters are identified with the HTML form element names and shall be passed to the gazetteer service using the KVP (Key-value pairs) convention (parameterName1=value1¶meterName2=value2&…).

The client must also append at the end of the URL the format of the requested response (xml, json or jsonp). Eg: query/dls.?section=&township=&range=&meridian=&province=

Using example values (eg): query/dls.xml?section=12&township=023&range=10&meridian=W4&province=sk http://gin.gwinfo.net/service/ngwds/en/gazetteer/query/dls.xml?section=12&township=023&range=10&meridian=W4

Important: note that in EPSG:4326, the axis order is y,x Result: In XML 12-023-10-W4 50.9429443615949 -111.272427830342 50.9356117248535 -111.284034729004 50.9502754211426 -111.26082611084

12

GIN DT-12-001 In JSON {"gazetteer": [ { "id":"12-023-10-W4", "name":"12-023-10-W4", "location":{ "type":"Point", "coordinates":[50.9429443615949 -111.272427830342], "locationtype":"estimated" }, "boundedby": { "type":"Envelope", "coordinates":[[50.9356117248535,-111.284034729004][50.9502754211426,111.26082611084]], "locationtype":"observed" } }, ...] }

2.3 Other provinces Ontario and British Columbia also have land gazetteers. In fact, BC can be queried using DLS but also using townships (this is why BC is queried in DLS and also has its own gazetteer service). The operations on those gazetteers are essentially the same except for the parameters list (the result structure remains the same) Ontario Gazetteer id: Ontario Parameters:  township  concession  lot Example: http://gin.gwinfo.net/service/ngwds/en/gazetteer/query/ontario.xml?township=Sherborne&concession=5&lot=14

British Columbia Gazetteer id: bc Parameters:  name Example: http://gin.gw-info.net/service/ngwds/en/gazetteer/query/bc.xml?name=kootenay

13

GIN DT-12-001

3. Gin General Gazetteer Client 3.1 Introduction The 3G API can be integrated in various web applications by adding a simple and free Javascript based 3G Client based on JQuery2 and HTML5 technology. 3.2 Implementation of the 3G Client In your web page, add the following script links just before the "closing" tag:

The current configuration uses JQUERY2 and JQueryUI1.10 located on Google servers. If you wish, you may download these scripts locally and make the necessary corrections to the source locations. Download the "gazetteerClient_v3.0.0.js" script on your web server and redirect the script code to point to your copy of the Gazetteer client Javascript file. Code source: http://gin.gw-info.net/service/ngwds/gazetteer/client/js/gazetteerClient_v3.0.0.js Add a “gazetteersApi” ID to the html element in your web page that will contain the 3G application. Ex: IMPORANT: A page can only host one 3G client per page. Future enhancement will enable multiple clients per web page. 3.3 Configuration The 3G client has several optional and mandatory configurations. The client is configured with attributes declared in the “gazetteersApi” identified html element. Examples:   



MANDATORY attributes:  id: Must be "gazetteersApi"  locale: English "en" or French "fr".  resultOutput:

14

GIN DT-12-001 o "inline": will display results inline in API HTML (Default configuration if left blank). o "off": will not display results and use custom callback (see below). o Any other value: will display results in your customized HTML tag with the specified "id" attribute. Ex: OPTIONAL attributes:  collapsibleTitle: String title for your "optionally collapsible" gazetteer interface.  filter: Gives access to predefined subsets of gazetteers (Ex: "gin" or "troo"). You may also declare a custom collection of services. To do so just add an array of service IDs (Ex: " ['wellid','province','nts'] "). If filter attribute is absent or left blank, all gazetteer services will be available.  callback: Enables you to send the spatial Gazetteer Object result to a custom javascript function: Parameter is the name of your custom function. WARNING: "resultOutput" attribute must be set to "off" to use this function.  autolaunch : (0|1) default = “1”. When the gazetteers only have a single result, it automatically launches the callback (see previous attribute). This behaviour can be disabled using autolaunch = “0”. If the parameter is absent, it is considered that autolaunch = “1”. 3.4 Callback function When declaring a callback function (see section 3.3 - Optional Attributes), the gazetteer API sends back a JSON formatted spatial object. Eg: {"gazetteer": [ { "id":"024L12", "name":"024L12 - Échelle: 50000", "centroid": {"type":"Point","coordinates":[58.625,-71.75], "locationtype":"estimated"}, "boundedby": {"type":"Envelope","coordinates":[[58.5,-72.0],[58.75,-71.5]], "locationtype":""} } ]}

IMPORTANT: Note that the "centroid" is mandatory while "boundedby" is only present when available. 3.4 Client DOM and CSS Using the client DOM element “ids” and “classes” it is possible to manipulate the “look and feel” (skin) of the 3G client application by adding your own CSS styling. Ex: