Requires GpsGate Server version 2.2.0.1648 to version 2.3.1.2076:

Here is a sample on how to write a “Geocoder Provider” plugin for reverse geocoding coordinates into addresses, and how to activate it for a VehicleTracker application. By creating your own geocoder provider you can integrate for example an external online reverse geocoding service, or a local database of addresses, into VehicleTracker.

Some background on geocoding and how GpsGate Server makes use of it in VehicleTracker.
Geocoding is the process of translating addresses into coordinates, while the opposite process is that of translating coordinates into addresses and is called reverse geocoding. VehicleTracker provides reverse geocoding through the use of a Geocoder object. The geocoder uses a set of geocoder providers to serve its requests. The geocoder queries its geocoder providers in an ordered fashion until all coordinates have been translated or until all geocoder providers have been queried.

By default, each VehicleTracker application is added to a default geocoder (named “Default VehicleTracker Geocoder”). The VehicleTracker default geocoder uses two geocoder providers: a local cache and a Google geocoder provider. You can create and use your own geocoder provider either by adding it to the default geocoder, or by creating a new geocoder. This sample shows you how to create a new geocoder and make it use the cache and your new geocoder provider.

Coding:
First, you should create a new class that extends the abstract class GeocoderProvider. Your class will be a ‘Loadable’ class, which means that it will be found and loaded into the system by a scan performed when the Franson NMEA Service is started. A row in the table ‘loadable_types’ will be created. Below is some sample code of a geocoder provider implementation.

using System.Collections.Generic;
using Franson.Reflection;
using Franson.Geo.Geocoding;
using Franson.Geo;

namespace Some.Namespace
{
    /// <summary>
    /// A sample geocoder provider to provide reverse geocoded locations
    /// </summary>
	[Loadable]
	public class SampleGeocoderProvider : GeocoderProvider
	{
		public SampleGeocoderProvider()
			: base()
		{
		}

		/// <summary>
		/// Queries an external reverse geocoder service to return a ReverseGeocoderResult.
		/// </summary>
		/// <param name="lstPositions">List of positions to reverse geocode</param>
		/// <returns>Struct containing list of <see cref="Location"/>s together with a status code</returns>
		public override ReverseGeocodeResult ReverseGeocode(List<Position> lstPositions)
		{
			//Make a web request and retreive the reverse geocode response here.
			//Parse the response into a list of Franson.Geo.Location objects, which are returned in the ReverseGeocodeResult.
			List<Location> lstLocations = new List<Location>(); //add the parsed response
			lstLocations.Add(new Location(new Position(1, 1), "Germany", "Hamburg", "12345", "Bornholmer Strasse", "12", "Box 123", "WasserStrasse 12, 12345 Hamburg, Germany"));
			
			ReverseGeocodeResult revGeocodeResult = new ReverseGeocodeResult(lstLocations, 200, lstPositions.Count, Name);
			return revGeocodeResult;
		}

		public override string Name
		{
			get { return "Sample Geocoder Provider"; }
		}
	}
}

Make reference to the following DLLs (you find them in the “[install_path]\IIS\bin” folder):

Franson.dll

Make sure your project references the same version of the DLLs as the GpsGate Server installation uses.

Build your project and copy your DLL to the [install_path]\Franson NMEA Service\ directory as well as to the [install_path]\IIS\bin directory. Restart the Franson NMEA Service to scan and load your Loadable type (your geocoder provider) into the system.

Database modifications:
To make use of your geocoder provider for an application you need to edit the database to create a new geocoder that uses the your geocoder provider (alternatively you could add your geocoder provider to the default geocoder but this sample shows how to create and use a new geocoder for the application). The following are SQL scripts for MSSQL and MySQL to do the needed additions to the database tables. You need to replace the below text ‘USE_YOUR_APPLICATION_ID_HERE’ with the application ID you want to activate the geocoder for.

1. Add a row to the table ‘geocoder’ and set its name.

MSSQL:

INSERT INTO geocoder(name, [description], bo_type) VALUES('New Geocoder', 'A new Geocoder', 'Franson.Geo.Geocoding.GeocoderWriter');

MySQL:

INSERT INTO geocoder(name, description, bo_type) VALUES('New Geocoder', 'A new Geocoder', 'Franson.Geo.Geocoding.GeocoderWriter');

2. Add a row to the table ‘geocoder_provider’ for each GeocoderProvider that you wish to use in the geocoder.
Set geocoder_id to the id that was created in step 1. Set type_id to the type of the geocoder provider you wish to have (check the table ‘loadable_type’ for the type_id of the geocoder provider). Set priority of the geocoder provider, this is the order in which the geocoder provider is queried by the geocoder. If you wish to use the geocoder cache provider, it should preferrably have priority 0 to query it first. This way, results from other providers will be cached.

The below script adds two geocoder providers to the geocoder; first the cache and then the newly created SampleGeocoderProvider.

MSSQL:

INSERT INTO geocoder_provider(geocoder_id, [type_id], priority) VALUES(
(SELECT geocoder_id FROM geocoder WHERE name='New Geocoder'),
(SELECT [type_id] FROM loadable_type WHERE [type_name]='Franson.Geo.Geocoding.Providers.CacheGeocoderProvider'),
 0);
INSERT INTO geocoder_provider(geocoder_id, [type_id], priority) VALUES(
(SELECT geocoder_id FROM geocoder WHERE name='New Geocoder'),
(SELECT [type_id] FROM loadable_type WHERE [type_name]='Some.Namespace.SampleGeocoderProvider'),
 1);

MySQL:

INSERT INTO geocoder_provider(geocoder_id, type_id, priority) VALUES(
(SELECT geocoder_id FROM geocoder WHERE name='New Geocoder'),
(SELECT type_id FROM loadable_type WHERE type_name='Franson.Geo.Geocoding.Providers.CacheGeocoderProvider'),
 0);
INSERT INTO geocoder_provider(geocoder_id, type_id, priority) VALUES(
(SELECT geocoder_id FROM geocoder WHERE name='New Geocoder'),
(SELECT type_id FROM loadable_type WHERE type_name='Some.Namespace.SampleGeocoderProvider'),
 1);

3. Add a row to the table ‘geocoder_application’, set the id of the application and geocoder.
MSSQL and MySQL:

INSERT INTO geocoder_application(geocoder_id, application_id) VALUES(
(SELECT geocoder_id FROM geocoder WHERE name='New Geocoder'),
USE_YOUR_APPLICATION_ID_HERE
);

4. Add an application setting to specify the new geocoder for the application.
Add a row to the table ‘settings’, create a setting named ‘GEOCODER_NAME’ and set its value to your new geocoder name. Link the setting to your application in the table ‘app_settings’.
MSSQL:

INSERT INTO settings(bo_type, [namespace], value_name, value_type, value_data, [description]) VALUES(
'Franson.Directory.ApplicationSettings',
'gpsgateserver',
'GEOCODER_NAME',
'System.String',
'New Geocoder',
'This application setting specifies the new geocoder for an application.'
);
INSERT INTO app_settings(setting_id, application_id) VALUES(
(SELECT setting_id FROM settings WHERE value_name='GEOCODER_NAME'),
USE_YOUR_APPLICATION_ID_HERE
);

MySQL:

INSERT INTO settings(bo_type, namespace, value_name, value_type, value_data, description) VALUES(
'Franson.Directory.ApplicationSettings',
'gpsgateserver',
'GEOCODER_NAME',
'System.String',
'New Geocoder',
'This application setting specifies the new geocoder for an application.'
);
INSERT INTO app_settings(setting_id, application_id) VALUES(
(SELECT setting_id FROM settings WHERE value_name='GEOCODER_NAME'),
USE_YOUR_APPLICATION_ID_HERE
);

Your VehicleTracker application will now use the new geocoder. Remember to recycle the application pool in IIS since application settings are cached.

If you want to go back to using the “Default VehicleTracker Geocoder” for the application, just delete the row in table ‘settings’ created in step 4.

MSSQL and MySQL:

DELETE FROM settings WHERE value_name='GEOCODER_NAME';

Note. If you don’t want to use an application setting to control which geocoder to use you can as an alternative to step 4 delete the row in table ‘geocoder_application’ linking your application to the “Default VehicleTracker Geocoder” and leave only the relation to your new geocoder so that it is found when the VehicleTracker application retreives the geocoder from the database.

Comments

Add a comment

Blog categories