**Using NBII Gazetteer Service**

Onkar Chandel

USGS-NBII

(703)-648-4185

<ochandel@usgs.gov>

Date: December 10, 2005

This document describes how to integrate NBII Gazetteer service into a
web-based application. NBII Gazetteer service is HTPP based service and
requires HTTP communication between NBII Gazetteer server and its client
i.e. the application requesting the service. Sample simple client
consuming NBII Gazetteer Service is available at

> <http://hoosier.cr.usgs.gov/services/gaz>

Sample fancy client consuming NBII Gazetteer service is available at

> <http://hoosier.cr.usgs.gov/services/gazf>

NBII Gazetteer Service URL is

<http://nbii-catalog.ornl.gov/wes/NBII/service/gazetteer/nbiiGazetteerSearch.jsp>

**Pre-requisite:**

Your web-site must be accessible by NBII Catalog Service server or it
will not be able to communicate gazetteer bounding boxes.

**Limitations:**

Projection of returned bounding box is 'WGS 84'. Other projections and
custom projection are yet to be supported.

**NBII Gazetteer Service Input Parameters:**

NBII Gazetteer service requires that client must pass 'nbiiCBURL'
parameter specifying a callback URL for receiving 'bounding box result'
from the gazetteer service. In any HTML file a call to Gazetteer service
can be made using URL similar to given below.

location
=\"http://nbii-catalog.ornl.gov/wes/NBII/service/gazetteer/nbiiGazetteerSearch.jsp?***nbiiCBURL**=http://www.yourserver.com/yourapp/gaz/rcvBBox.htm*\"\'

Receiver page can be written in JSP, ASP, PHP or HTML.

**NBII Gazetteer Service Output Parameters:**

NBII Gazetteer Service sends back following parameters

maxx -- containing max x coordinate.

maxy -- containing max y coordinate.

minx -- containing min x coordinate.

miny -- containing min y coordinate.

Receiver page can get these parameters and pass or use them as per
applications requirement.

**Sample Client for NBII Gazetteer Service:**

Sample client contains two files. One is for calling gazetteer service
and other for receiving response from gazetteer service.

***index.htm:***

This file can be renamed as per requirements of the applications. It can
reside in any folder of the application, however for maintainability it
should be copied into a separate folder called 'gaz'.

This file calls NBII Gazetteer service and sends back callback URL for
receiving results. 'nbiiCBURL' parameter must be changed for receiving
results from gazetteer service. This parameter can point to either
rcvBBox.htm or any file of your choice. This file can be called under
frames or in a new pop-up window. Result will be received in the
window/frame this file is opened.

***rcvBBox.htm:***

This file facilitates receiving bounding box coordinates from NBII
Gazetteer Service. This file contains bare minimum code for showing how
to receive coordinates from the service. It should be modified as per
application requirements.

**Gazetteer Service Client for HTML Viewer applications:**

This section describes how to integrate Gazetteer Service client for
zooming into a place into HTML Viewer application.

For achieving this, following steps should be followed.

1)  Download Gazetteer service client for HTML Viewer, i.e.
    GazetteerServiceClientForHTMLViewer.zip file.

2)  Unzip above file under HTML Viewer application's folder. It will
    create a gaz directory and put client files into it.

3)  Modify 'nbiiCBURL' parameter (in index.htm file) for pointing to
    rcvBBox.htm file. More information is given in 'Sample Client for
    NBII Gazetteer Service' section.

4)  Uncomment window.close () in rcvBBox.htm file, if gazetteer service
    is opened in new window. This will help closing of the window. And
    comment location='text.htm'

5)  If Gazetteer Window is opened in 'TextFrame', modify
    location='text.htm' to application specific file, if required.

6)  Add new tool in toolbar.htm for invoking gazetteer service. Action
    of that tool should either call 'gaz/index.htm' in new window or in
    any frame of HTML viewer window.

**Description of Client Zip Files:**

  -------- ----------------------------------------- -------------------------------
  **1.**   GazetteerServiceClientForHTMLViewer.zip   This zip file contains
                                                     Gazetteer Service client files
                                                     for HTML Viewer applications.

  **2.**   GazetteerServiceClient.zip                This zip file contains
                                                     Gazetteer Service client files
                                                     for a very simple and bare
                                                     minimum client. This client is
                                                     most simple and can be enhanced
                                                     for any application.

  **3.**   GazetteerServiceClientFancy.zip           This zip file contains
                                                     Gazetteer Service client files
                                                     for a fancy client, however
                                                     this client is more difficult
                                                     to enhance and it's integration
                                                     is little bit difficult too.
  -------- ----------------------------------------- -------------------------------