Geocoder Integration with GpsGate Server using HTTP

This article will demonstrate how to integrate a geocoding service over HTTP with GpsGate Server. A simple xml-based protocol is defined which allows for 3rd party integration. We show how to configure GpsGate Server to communicate with the geocoding service, and how to use the appropriate tools to test the integration.

 

Introduction

GpsGate Server includes several types of geocoder providers out-of-the-box. For example, Point-of-Interest, Geofence, Google, and more. There is also an encoder available that can be configured to make web service requests to an URL using a simple xml-based protocol. It is called “HTTP Geocoder”. With this geocoder, a 3rd party integration can be made by implementing a web service using, for example, PHP, JSP, or any other script-engine for dynamically-generated web pages. The following examples will use a fictitious web service, MyMap, implemented using PHP and located at http://your-server.com/Geocoder.php.

Protocols

Reverse Geocoding Protocol

When the MyMap geocoder provider does a reverse geocoding request, it will use the following URL format:


http://your-server.com/Geocoder.php?op=ReverseGeocode&longitude=103.851718&latitude=1.290655


The part in bold is configurable, as we’ll see in a moment.

The result of the request is expected to be xml with the following format:

1
2
3
4
5
6
7
8
9
10
11
<Location>
  <Address>Address</Address>
  <AdministrativeAreaName>AdministrativeAreaName</AdministrativeAreaName>
  <CityName>CityName</CityName>
  <CountryName>CountryName</CountryName>
  <PostalCodeNumber>PostalCodeNumber</PostalCodeNumber>
  <StreetBox>StreetBox</StreetBox>
  <StreetName>StreetName</StreetName>
  <StreetNumber>StreetNumber</StreetNumber>
  <SubAdministrativeAreaName>SubAdministrativeAreaName</SubAdministrativeAreaName>
</Location>

The recognized elements within the Location element are: Address, AdministrativeAreaName, CityName, CountryName, PostalCodeNumber, StreetBox, StreetName, StreetNumber, SubAdministrativeAreaName, Longitude, Latitude, and Altitude.

Geocoding

A geocoding request is performed similarly. Here we send a query using the following URL format:

http://your-server.com/Geocoder.php?op=Geocode&Query=CITY+HALL

The result is expected to be a list of locations:

1
2
3
4
5
6
7
8
9
10
11
12
<LocationList>
  <Location>
    <Longitude>103.851717793137</Longitude>
    <Latitude>1.29065480099533</Latitude>
    <Address>CITY HALL</Address>
  </Location>
  <Location>
    <Longitude>103.852542627029</Longitude>
    <Latitude>1.29298990999197</Latitude>
    <Address>CITY HALL MRT STATION</Address>
  </Location>
</LocationList>

 

Testing

Within an application we can now test the MyMap geocoder. Drop the “Request Address” pin onto the map at a desired location:

reverse-geocoding1.png

The result is a success.

Conclusion

This concludes the walk-through on how to integrate a 3rd party geocoding service. The configuration within GpsGate Server is quite simple and all the tools for testing are available. What remains is to create an integration service using a server-side scripting language of your choice (or any server technology for that matter).