WES Gazetteer

Introduction

WES Gazetteer is a standards-based gazetteer service that provides world coverage for name look-up services. The gazetteer content is pre-populated in Oracle tables and is composed of content from the following sources:

NGA Gazetteer - The National Geospatial-Intelligence Agency’s database of foreign geographic feature names. Coverage is worldwide, excluding the United States and Antarctica.
Geographic Names Information System (GNIS) - Developed by the USGS in cooperation with the U.S. Board on Geographic Names (BGN), contains information about almost 2 million physical and cultural geographic features in the United States.

WES Gazetteer is based upon the OGC Web Gazetteer Service (WFS-G) specification [OGC 05-035r2]. This specification is a specialized Web Feature Service (WFS) that provides additional capabilities specific to a gazetteer-like feature collection. WES Gazetteer uses the OGC WFS-G specification interface for accessing the WES Gazetteer database.

WES Gazetteer defines a set of location instances, each of which provides a binding between representations of a location and an identifier. Each location instance is a feature, and is a (possibly one of many) representation of a “real-world” object. The representation of the real-world object within the Gazetteer is designed to be used to perform this translation and to allow the set of such Features to be discovered and searched. The Gazetteer service is thus a WFS serving a predictably structured set of features representing Gazetteers and the sets of location instances they contain. The WES Gazetteer Service allows a client to search and retrieve elements of a georeferenced vocabulary of well-known place-names. This profile extends the WFS interface in a way that a client is able to:

Determine if a WFS implementation is acting as a Gazetteer Service;
Query the Gazetteer Service in order to retrieve place-name features without closer examination of the feature type definitions; and
Access metadata about the gazetteer(s) provided by the service.

This International Standard defines the implementation of the WFS-G using the Hypertext Transfer Protocol (HTTP) and supports two request methods: GET and POST. Please see the example Gazetteer interface below.

Note: Refer to the OGC WFS-G specification and the OGC WFS specification for details on gazetteer operations and associated XML Schema. Each of the WFS-G operations supported for gazetteer access are described below:

Gazetteer Query Interface

Formatting the XML Query

top
The POST message sent to the Gazetteer service has a XML encoded portion. This XML string has with it information about the query.

Here is an example XML Query constructor Javascript function:

var index = form.region.selectedIndex;
var reg = form.region.options[index].value;
var place = form.placename.value;

    form.gazQuery.value =
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
           + "<gazetteer-service "
           + "xmlns=\"" + url + "\" "
           + "version=\"1.1\"> "
           + "<query-request> "
           + " <gazetteer-query> "
           + "    <name-query operator=\"contains-phrase\" "
           + "      text=\"" + place + "\" "
           + "   region=\"" + reg + "\"/> "
           + " </gazetteer-query> "
           + "</query-request> "
           + "</gazetteer-service>";

Using the example interface above gives you a good idea of how to construct an HTML page to query the gazetteer interface, and how to use a Javascript function like the one above to format an XML string to be sent.

How to use the Java Client

top

A short example of how to use the java client code can be found here.

The following variables have been hardcoded in the example for illustration purposes:


					String placeName = "Corner Brook";

					String region = "WORLD";

					String regionText = "";

					String endpoint = "http://localhost/wes/gazetteer/wfs-g";

					String username = "";

					String responseXml = "";

A GazetteerClient object is created as follows, taking the request, username of the current user, and Gazetteer URL as parameters:


					GazetteerClient gazetteerClient = GazetteerClient.getInstance(request, username, new URL(endpoint));

Once this is done, a search can be executed, using a place name and a region as parameters. The response is stored in the responseXml object created earlier:


					responseXml = gazetteerClient.search(placeName, region);

If the method call above generated a String response, the search was completed successfully (whether or not the search generated results). The responseXml variable should now hold the XML response. Otherwise, an error has occurred.

This example generates the following XML response:

<?xml version="1.0"?>
<gazetteer-service version="1.0" xmlns="http://ngis.compusult.net/weslet/gazetteer-response">
    <query-response>
        <gazetteerEntry>
            <identifier>wesgaz-1-799094-03</identifier>
            <name>Corner Brook</name>
            <description>Corner Brook, Newfoundland, CANADA</description>
            <centerof>
                <point srsname="EPSG:4326">
                    <coordinates>48.95,-57.9333333</coordinates>
                </point>
            </centerof>
            <sizeInKm>250.0</sizeInKm>
        </gazetteerEntry>
    </query-response>
</gazetteer-service>

This XML response is parsed using the following code. The JSTL tags are used to extract the result name and value from the XML, and the java variables are used to save the values so that they can be displayed on the page:


			<%

			    String resultName = "";

			    String resultValue = "";

			%>

			    <x:forEach	select="$doc/*/query-response/gazetteerEntry" var="gazEntry">

			        <c:set var="resultValue">

			            <x:out select="string($gazEntry/centerof/point/coordinates)" />###

			            <x:out select="string($gazEntry/sizeInKm)"/>

			        </c:set>

			        <c:set var="resultName">

			            <x:out select="string($gazEntry/description)" />

			        </c:set>

			<%

			    resultName = (String)pageContext.getAttribute("resultName");

			    resultValue = (String)pageContext.getAttribute("resultValue");

			%>

			    </x:forEach>

This is what this example looks like:

Test Interface