Fork me on GitHub

Gisgraphy user guide

Gisgraphy user guide


To suggest a change or a correction to any part of the documentation, please send a mail to David Masclet.
Quick access to webservices documentation :
Geocoding | Address parser | Reverse geocoding | Street service | Find nearby | Fulltext
Table of contents :
[top]

Introduction

[top]

Version

This documentation is for the current version of Gisgraphy (snapshots, nightly builds, and "not-released yet" versions included), you can find documentation for older versions here
[top]

About

Since 2006, Gisgraphy has been a free, open-source framework that offers the ability to do geolocalisation and geocoding via Java APIs or REST webservices. Because geocoding is nothing without data, it provides an easy-to-use importer that will automagically download and import the necessary (free) data to your local database (OpenStreetMap, GeoNames and Quattroshapes : more than 100 million entries). You can also add your own data with the Web interface or the import connectors provided. gisgraphy is production ready and has been designed to be scalable (load balanced), high-performance and used in other languages than just Java : results can be output in XML, JSON, PHP, Python, Ruby, YAML, GeoRSS, and Atom. One of the most popular GPS tracking systems (OpenGTS or Traccar) also includes a Gisgraphy client...Gisgraphy is a framework. As a result it's flexible and powerful enough to be used in a lot of different use casesread more Here are the main functionalities :
  • Importers for OpenStreetMap and Quattroshapes data in CSV format (view data)
  • Importers from GeoNames CSV files. Just give the country(ies) you wish to import and / or the placetypes, and Gisgraphy will download the files and import them with all the alternateNames (optional), and sync the database with the fulltext search engine
  • Worldwide geocoding / worldwide reverse geocoding / street search WebServices;
  • REST WebService
  • Powerful Autocompletion / suggestion engine
  • Leaflet plugins and JS API (aka : Gisgraphy-js-API)
  • Several output formats supported : XML, JSON, PHP, Ruby, Python, Atom, RSS / GeoRSS, YAML
  • Full text search (based on Lucene / Solr with default filters optimized for city search (case insensitivity, separator characters stripping, ..) via an Java API or a webservice
  • Find nearby function (with limits, pagination, restrict to a specific country and/or language and other useful options) via a Java API or a web service
  • An admin / back office with statistics interface
  • Fully replicated / scalable / high performance / cached services
  • Search for ZIPcode name, IATA, ICAO
  • Internationalized (with support of Cryllic, Arabic, Chinese,... alphabet)
  • Dojo widgets / prototype / Ajax to ease search but can be use it even if Javascript is not enabled on the client side
  • Opensearch module
  • Platform / language independent
  • Provides all the countries flags in svg and png format
[top]

Technical informations...

Please consult the developer guide
[top]

Quick start

Please consult the last quick start guide.
[top]

Requirements

  • 260 Gb of free disk space for all countries (+ 250 go for the raw files downloaded on the download server
  • Internet access to download data files (you can skip it)
  • Java 1.6 or greater
  • A 64 bit platform is strongly recommended since SolR uses Memorymap )
  • PostgreSQL with the PostGIS extension (It is HIGHLY recommended to have PostGIS 1.3.1 or greater for good performance... more.
  • 4G of Memory is required for the import process, it can be decreased to 2Gb for the webservice only. The amount of memory depends on the amount of data.
  • A servlet container if you want to use it as a Servlet (not programatically). Actually, Gisgraphy has been tested on Tomcat and Jetty but any Servlet container should be OK
[top]

Which technologies are used ?

  • Java
  • Maven 2
  • Spring
  • Hibernate
  • PostgreSQL / PostGIS
  • SolR / Lucene
  • Hibernate Spatial
  • Appfuse
  • Jquery / prototype
[top]

License

The Gisgraphy project (www.gisgraphy.com) is a free open-source project under the LGPL license V3. GeoNames data is under the creative commons attributions license.
[top]

Installation

[top]
Please go the the installation page
[top]

Import Data

To import data, you must use the admin interface. See the admin interface section for more information
[top]

Debug Mode

Each Gisgraphy service is a servlet. Each servlet can be run in debug mode. It enables the error message (exception message) to be output to the end user. To do so, just declare the servlet init parameter "debugMode" to true (in the web.xml) as shown :

<servlet>
		<servlet-name>address parser service</servlet-name>
		<servlet-class>
			com.gisgraphy.servlet.AddressParserServlet
		</servlet-class>
		 <init-param>
		 <!-- if true the output field error will contains the exception message.
			 Default to false -->
			<param-name>debugMode</param-name>
			<param-value>true</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>

<servlet>
		<servlet-name>geocoding service</servlet-name>
		<servlet-class>
			com.gisgraphy.servlet.GeocodingServlet
		</servlet-class>
		 <init-param>
		 <!-- if true the output field error will contains the exception message.
			 Default to false -->
			<param-name>debugMode</param-name>
			<param-value>true</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
</servlet>


<servlet>
		<servlet-name>street service</servlet-name>
		<servlet-class>
			com.gisgraphy.servlet.StreetServlet
		</servlet-class>
		 <init-param>
		 <!-- if true the output field error will contains the exception message.
			 Default to false -->
			<param-name>debugMode</param-name>
			<param-value>true</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>


<servlet>
		<servlet-name>geoloc service</servlet-name>
		<servlet-class>
			com.gisgraphy.servlet.GeolocServlet
		</servlet-class>
		 <init-param>
		 <!-- if true the output field error will contains the exception message.
			 Default to false -->
			<param-name>debugMode</param-name>
			<param-value>true</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
</servlet>
	
	
<servlet>
		<servlet-name>fulltext service</servlet-name>
		<servlet-class>
			com.gisgraphy.servlet.FulltextServlet
		</servlet-class>
		<init-param>
		 <!-- if true the output field error will contains the exception message.
			 Default to false -->
			<param-name>debugMode</param-name>
			<param-value>true</param-value>
		</init-param>
		<load-on-startup>2</load-on-startup>
</servlet>

	
[top]

Options and environment-specific settings

All the options and environment-specific settings are located in the env.properties file. The env.properties is located in the /webapps/ROOTWEB-INF/classes directory
Take care of white spaces in properties file : MyProperties=bar is not the same as MyProperties= bar (whitespaces after the equals sign are taken into account)
[top]

importer.geonames.dir

This option determines the directory where the GeoNames files are located. It must end with / or \ according to the operating system path separator. It is also the directory where the GeoNames files will be downloaded from the importer.geonames.downloadURL URL . On Windows, the '\' character must be escaped as in the example below. The path can be absolute or relative (from the directory where you've launch Gisgraphy). It is not recommended to put space in the path.
. This option is case sensitive if the underlying file system is case sensitive (e.g : Linux / Unix).
Examples on Linux :
importer.geonames.dir=./data/prod/
importer.geonames.dir=/home/user/data/prod/

Example on Windows
importer.geonames.dir=.\\data\\prod\\


[top]

importer.openstreetmap.dir

This option determines the directory where the OpenStreetMap files are located. It must end with / or \ according to the operating system path separator. It is also the directory where the OpenStreetMap files will be downloaded from the importer.openstreetmap.downloadURL URL . On Windows The '\' character must be escaped as in the example below. The path can be absolute or relative (from the directory where you've launch Gisgraphy). It is not recommended to put space in the path.
. This option is case sensitive if the underlying file system is case sensitive (e.g : Linux / Unix).
Examples on Linux :
importer.openstreetmap.dir=./data/prod/
importer.openstreetmap.dir=/home/user/data/prod/

Example on Windows
importer.openstreetmap.dir=.\\data\\prod\\


[top]

importer.geonames.zipcode.dir

This option determines the directory where the GeoNames zipcode files are located. It must end with / or \ according to the operating system path separator. It is also the directory where the GeoNames zipcode files will be downloaded from the importer.geonames.zip.downloadURL URL . On Windows The '\' character must be escaped as in the example below . The path can be absolute or relative (from the directory where you've launch Gisgraphy). It is not recommended to put space in the path.
. This option is case sensitive if the underlying file system is case sensitive (e.g : Linux / Unix).
Examples on Linux :
mporter.geonames.zipcode.dir=./data/prod/
mporter.geonames.zipcode.dir=/home/user/data/prod/

Example on Windows
mporter.geonames.zipcode.dir=.\\data\\prod\\


[top]

importer.geonames.enabled

Whether the importers related to GeoNames will be processed (it enable the zipcode importer too). If 'true' the importers will be executed. This option should be in lower case.
Examples :
importer.geonames.enabled=true
importer.geonames.enabled=false


[top]

importer.openstreetmap.enabled

Whether the importers related to OpenStreetMap will be processed. If 'true' the importers will be executed. This option should be in lower case.
Examples :
importer.openstreetmap.enabled=true
importer.openstreetmap.enabled=false


[top]

importer.openstreetmap.housenumber.enabled

Whether the importers related to house numbers OpenStreetMap will be processed. If 'true' the importers will be executed. This option should be in lower case.
Examples :
importer.openstreetmap.housenumber.enabled=true
importer.openstreetmap.housenumber.enabled=false


[top]

importer.quattroshapes.enabled

Whether the importers related to Quattroshapes will be processed. If 'true' the importers will be executed. This option should be in lower case.
Examples :
importer.quattroshapes.enabled=true
importer.quattroshapes.enabled=false


[top]

importerConfig.openstreetmap.fill.isin.field

Whether we search for the nearest city in GeoNames data to fill the is_in field. This will increase the run time of the importer but strongly increases the relevance of the geocoder. Default to true. This option should be in lower case.
Examples :
importerConfig.openstreetmap.fill.isin.field=true
importerConfig.openstreetmap.fill.isin.field=false


DON'T MODIFY this option after importer is done.


[top]

importer.geonames.downloadURL

This option determines the URL of the server to download the GeoNames files to be processed (typically, the GeoNames download server). This option is case sensitive.
Example :
importer.geonames.downloadURL=http://download.geonames.org/export/dump/


Don't forget the ending slash !


[top]

importer.openstreetmap.downloadURL

This option determines the URL of the server to download the OpenStreetMap files to be processed (typically, the Gisgraphy download server). This option is case sensitive.
Example :
importer.openstreetmap.downloadURL=http://download.gisgraphy.com/openstreetmap/


Don't forget the ending slash !


[top]

importer.openstreetmap.housenumbers.downloadURL

This option determines the URL of the server to download the house numbers OpenStreetMap files to be processed (typically, the Gisgraphy download server). This option is case sensitive.
Example :
importer.openstreetmap.downloadURL=http://download.gisgraphy.com/openstreetmap/housenumbers/


Don't forget the ending slash !


[top]

importer.openstreetmap.cities.downloadURL

This option determines the URL of the server to download the cities OpenStreetMap files to be processed (typically, the Gisgraphy download server). This option is case sensitive.
Example :
importer.openstreetmap.cities.downloadURL=http://download.gisgraphy.com/openstreetmap/cities/


Don't forget the ending slash !


[top]

importer.openstreetmap.pois.downloadURL

This option determines the URL of the server to download the POIs (point of interest) OpenStreetMap files to be processed (typically, the Gisgraphy download server). This option is case sensitive.
Example :
importer.openstreetmap.pois.downloadURL=http://download.gisgraphy.com/openstreetmap/pois/


Don't forget the ending slash !


[top]

importer.quattroshapes.downloadURL

This option determines the URL of the server to download the Quattroshapes files to be processed (typically, the Gisgraphy download server). This option is case sensitive.
Example :
importer.quattroshapes.downloadURL=http://download.gisgraphy.com/quattroshapes/


Don't forget the ending slash !


[top]

importer.geonames.zipcode.downloadURL

This option determines the URL of the server to download the GeoNames zipcode files to be processed (typically, the GeoNames download server). This option is case sensitive.
Example :
importer.geonames.zipcode.downloadURL=http://download.geonames.org/export/zip/


Don't forget the ending slash !


[top]

importer.geonamesfilesToDownload

This option determines the files to be downloaded from the importer.geonames.downloadURL URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip) and alternateNames.zip. This option is case sensitive. If the allCountries.txt file is in the importer.geonames.dir directory, the other country files will be logically ignored.
Examples :
importer.geonamesfilesToDownload=US.zip;MX.zip
importer.geonamesfilesToDownload=allCountries.zip


If you run an import, change the option and re-run an import : you must first delete the old downloaded file before you re-run the import. If you don't : the files you've downloaded for the first import will be processed.

It is not necessary to download CountryInfo.txt, iso-languagecodes.txt, because they are already in the gisgraphy data directory of the Gisgraphy distrib.


[top]

importer.openstreetmapfilesToDownload

This option determines the files to be downloaded from the importer.openStreetMap.downloadURL URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip). This option is case sensitive. If the allCountries.txt file is in the importer.geonames.dir directory, the other countries files will be logically ignored.
Examples :
importer.openstreetmapfilesToDownload=AD.tar.bz2;CY.tar.bz2
importer.openstreetmapfilesToDownload=allCountries.zip



[top]

importer.openstreetmapHouseNumberFilesToDownload

This option determines the house numbers files to be downloaded from the importer.openstreetmap.housenumbers.downloadURL URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip). This option is case sensitive. If the allCountries.txt file is in the importer.openstreetmap.housenumbers.dir directory, the other countries files will be logically ignored.
Examples :
importer.openstreetmapHouseNumberFilesToDownload=AD.tar.bz2;CY.tar.bz2
importer.openstreetmapHouseNumberFilesToDownload=allCountries.zip



[top]

importer.openStreetMapCitiesFilesToDownload

This option determines the OpenStreetMap cities files to be downloaded from the importer.openstreetmap.cities.downloadURL URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip). This option is case sensitive. If the allCountries.txt file is in the importer.openStreetMapCitiesFilesToDownload directory, the other countries files will be logically ignored.
Examples :
importer.openStreetMapCitiesFilesToDownload=AD.tar.bz2;CY.tar.bz2
importer.openStreetMapCitiesFilesToDownload=allCountries.zip



[top]

importer.openStreetMapPoisFilesToDownload

This option determines the POIs (point of interest) numbers files to be downloaded from the importer.openstreetmap.pois.downloadURL URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip). This option is case sensitive. If the allCountries.txt file is in the importer.openstreetmap.pois.dir directory, the other countries files will be logically ignored.
Examples :
importer.openStreetMapPoisFilesToDownload=AD.tar.bz2;CY.tar.bz2
importer.openStreetMapPoisFilesToDownload=allCountries.zip



[top]

importer.quattroshapesFilesToDownload

This option determines the Quattroshapes files to be downloaded from the importer.quattroshapes.downloadURL URL. The files must be ';' separated. typically the file is shapes.tar.bz2. This option is case sensitive. Files will be downloaded in importer.quattroshapes.dir directory.
Examples :
importer.quattroshapesFilesToDownload=shapes.tar.bz2



[top]

importer.retrieveFiles

Whether the files defined by the importer.*filesToDownload option should be downloaded. If 'true' the importer will download the files. If 'false', it will use the files already present. This option should be in lower case.
Examples :
importer.retrieveFiles=true
importer.retrieveFiles=false


[top]

fulltextSearchUrl

The URL of the SolR Server. If you use the SolR server of the Gisgraphy distribution : the URL should be the Gisgraphy URL follow by SolR (name of the war file). If you need better performance, (that's to say, run Gisgraphy and the SolR server in two distinct JVM) see JVM optimisation) : specify the URL of the server you want to use. This option is case sensitive.
Examples :
fulltextSearchUrl=http://localhost:8080/SolR/

Example with the default SolR port
fulltextSearchUrl=http://localhost:8983/SolR/


[top]

importerConfig.wrongNumberOfFieldsThrows

Whether the importer should throw an exception and stop the import if a line in an imported CSV file doesn't have the expected number of fields. This option should be in lower case. Recommended to be set to false; set it to true if you use Gisgraphy for error correction.
Examples :
importerConfig.wrongNumberOfFieldsThrows=true
importerConfig.wrongNumberOfFieldsThrows=false


[top]

importerConfig.missingRequiredFieldThrows

Whether we should throw an exception and stop the import if a required field is missing. This option should be in lower case. Recommended to be set to false, set it to true if you use Gisgraphy for error correction.
Examples :
importerConfig.missingRequiredFieldThrows=true
importerConfig.missingRequiredFieldThrows=false


[top]

importerConfig.acceptRegExString

A regular expression for the place type we want to import. The default value is .* (all the place types) if the value is not specified. Administrative divisions and countries are automatically imported. This option is case insensitive. Place types are the name of the entities class (see package com.gisgraphy.domain.geoloc.entity source code for details) - don't forget to add GISFEATURE for POIs that are not categorized.
Examples :
.* : import all gisfeatures, no matter their feature class / code
RESTAURANT|BAR : import all Restaurants and Bars
RESTAURANT|BAR|GISFEATURE : import all Restaurants and Bars and POI that have no real categories
FOREST : import all the forests


See http://download.geonames.org/export/dump/featureCodes.txt to get a full description of the feature class / code. This page gives you details on what the "feature codes" used in GeoNames are.


[top]

importerConfig.tryToDetectAdmIfNotFound

If this option is set to (recommended value) true : The importer will try to detect Adm for features if the AdmXcodes values does not correspond to a known Adm. Set this option to true to activate error correction. If set to false, error correction is disabled and if no Adm is found for the AdmXcode, the feature will be linked to a null Adm.

This option is case sensitive and must be set in lower case. Example : There is an adm with level 2 which have adm1Code = 'A1' and adm2Code = 'B2' in the datastore. Suppose there is a gisFeature which have Adm1code='A3' and Adm2Code='B2', Gisgraphy will detect an error because there is no Adm with those codes. So if this option is set to true, Gisgraphy will correct the error and will link the feature to the Adm with codes adm1Code = 'A1' and adm2Code = 'B2'. If if this option is set to false, Gisgraphy won't try to correct the error, puts a warning message in the logs, and links the feature to a null Adm. This option should be in lower case.
Examples :
importerConfig.tryToDetectAdmIfNotFound=true
importerConfig.tryToDetectAdmIfNotFound=false


[top]

importerConfig.syncAdmCodesWithLinkedAdmOnes

This option is a little bit difficult to understand. An example is often simpler than a big speech ;). First, there is a few things you need to know : a feature has the following properties:
FeatureId......Adm...Adm1Code...Adm2Code...Adm3Code...Adm4Code...adm1Name...Adm2Name...adm3Name...Adm4Name...
An Adm is a feature too and has the same properties.
So, a feature is linked to an administrative division (AKA : Adm). For performance reasons, the codes and names of the Adms are stored in the Feature itself.
Now consider the example above : if there is an error the adm will not be the same as the codes in the CSV files. This option allow you to choose between two strategies :
  • If importerConfig.syncAdmCodesWithLinkedAdmOnes is set to 'true', then the admXcodes and admXnames of the features will be the same as the linked Adm One (in our example : if importerConfig.tryToDetectAdmIfNotFoundis set to 'true' the adm1Code will be 'A1' and the Adm2Code will be 'B2' - that's to say the same as the Adm ones)
  • If importerConfig.syncAdmCodesWithLinkedAdmOnes is set to 'false', the admXcodes and admXnames of the features will be the same as the CSV file (in our example : if importerConfig.tryToDetectAdmIfNotFound is set to 'true', the adm1Code will be 'A3' and the Adm2Code will be 'B2' - and the linked Adm will be null)
In other words if you want the importer to set the admXcode and admXnames to the CSV one : set this option to false. if you want those codes to be the same as the linked Adm : set it to true.
If you don't know what to do : set it to the recommended value : true. This option is case sensitive and must be set in lower case.
importerConfig.tryToDetectAdmIfNotFound and importerConfig.syncAdmCodesWithLinkedAdmOnes are orthogonal concepts


[top]

importerConfig.admXExtracterStrategyIfAlreadyExists

In order to import the Adm before the other features, Gisgraphy extracts Adm1, Adm2, Adm3 and Adm4 into separate files. This option tells Gisgraphy what to do if an AdmX file (determined with the importerConfig.admXFileName option) already exists in the importer.geonames.dir. This option is case sensitive. 3 options are available :
  • skip : extraction will be skipped, and the existing file will be used;
  • backup : The already existing file will be backed up (with the date and the current time) and a new file will be extracted and used;
  • reprocess : the file will be replaced by the new one
Examples :
importerConfig.adm3ExtracterStrategyIfAlreadyExists=reprocess
importerConfig.adm4ExtracterStrategyIfAlreadyExists=skip


[top]

importerConfig.adm1FileName

Specifies the filename of the CSV file with Administrative division with level 1. Should normally be 'admin1Codes.txt'. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.adm2FileName

Specifies the filename of the CSV file with Administrative division with level 2. Should normally be 'admin2Codes.txt'. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.adm3FileName

Specifies the filename of the CSV file with Administrative division with level 3. Should normally be 'admin3Codes.txt'. This file name will be used to extract Adm with level 3. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.adm4FileName

Specifies the filename of the CSV file with Administrative division with level 4. Should normally be 'admin4Codes.txt'. This file name will be used to extract Adm with level 4. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.languageFileName

Specifies the filename of the CSV file with languages. Should normally be 'iso-languagecodes.txt'. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.countriesInfosFileName

Specifies the filename of the CSV file with country information. Should normally be 'countryInfo.txt'. This option is case sensitive if the underlying file system is case sensitive. This option is not the list of countries to import.

To be clearer the option importerConfig.countriesFileName has been renamed to 'importerConfig.countriesInfosFileName' (version >= 2.0)
[top]

importerConfig.alternateNamesFileName

Specifies the filename of the CSV file that contains alternate names. Should normally be 'alternateNames.txt'. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.alternateNameFeaturesFileName

Specifies the name of the file where the alternate names of features that are not adm1, adm2, or country are (extracted). Should normally be 'alternateNames-features.txt'. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.alternateNameAdm1FileName

Specifies the the name of the file where the alternate names of adm with level 1 are (extracted). Should normally be 'alternateNames-adm1.txt'. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.alternateNameAdm2FileName

Specifies the the name of the file where the alternate names of adm with level 2 are (extracted). Should normally be 'alternateNames-adm2.txt'. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.alternateNameCountryFileName

Specifies the name of the file where the alternate names of countries are. Should normally be 'alternateNames-country.txt'. This option is case sensitive if the underlying file system is case sensitive.

[top]

importerConfig.importGisFeatureEmbededAlternateNames

The alternate names are provided in each country dump file, some additional information (languages, isPrefered name,...) are in a separate file. If you want to import the alternate names of the country files (faster but you miss some informations and the language parameter of the fulltext service won't be taken into account) set this option to true - in that case the importerConfig.alternateNamesFileName will be ignored. If you want a full import with the alternatenames separated file set this option to false. This option is case sensitive and must be set in lowercase.
Examples :
importerConfig.importGisFeatureEmbededAlternateNames=true
importerConfig.importGisFeatureEmbededAlternateNames=false


[top]

fulltextsearch.maxConnectionsPerHost

Limits the numbers of connections to the SolR server per host. Recommended : 32.

[top]

fulltextsearch.maxTotalConnections

Limits the numbers of connections to the SolR server for all hosts. Recommended : 128.

[top]

geolocsearch.defaultGeolocSearchPlaceType

Define the default placetype Class for the geoloc query (not the fulltext one). An empty or wrong value will search for any placetype by default. This option is case sensitive. The placeType must be in the entity package. Searching for all placetypes decreases performance if there are a lot of feature in the database. The name of the class should not ends with '.class' and is case sensitive.
Examples :
geolocsearch.defaultGeolocSearchPlaceType=City
geolocsearch.defaultGeolocSearchPlaceType=


[top]

addressParser.url

The url of the address parser server. This option is the one to change when you buy premium webservices. This must be a valid URL
Examples :
addressParser.url=http://services.gisgraphy.com/addressparser/parse?
[top]

useAddressParserWhenGeocoding

The option below enables/disables the parsing of the text to geocode. It can improve the response time because no requests are done to Gisgraphy (offline mode) . Case sensitive, should be in lowercase true|false, default to false.
Examples :
useAddressParserWhenGeocoding=true
useAddressParserWhenGeocoding=false

Note that address parser will be enabled if this option is true OR if the postal parameter is true. so you can disable the address parser by default and enable it at query time.
[top]

searchForExactMatchWhenGeocoding

Whether we should do a search with all words required AND a search without. It decrease the response time but can be useful if you want to search for common places (hotel, city, adm, monument) AND address. It allow you to do a fulltext search and a geocoding request. Default to true. Set to false if you only want to geocode #address, not place (better performance, less accuracy). Case sensitive, should be in lowercase true|false.
Examples :
searchForExactMatchWhenGeocoding=true
searchForExactMatchWhenGeocoding=false
Two versions are deployed : one on Gisgraphy server and one on Google appengine.


[top]

addressParser.class

The (Java) class of the address parser client. This option can be changed to fit your own implementation. This parameter is useful when you buy a license of the parser and use it internally (without the webservices)
Examples :
addressParser.class=com.gisgraphy.addressparser.AddressParserClient


[top]

spellchecker.enabled

Enable or disable the spellchecker for the fulltext search engine. 'true' or 'false' are possible values. This option is case sensitive.
Examples :
spellchecker.enabled=true
spellchecker.enabled=false
Spellchecking is available for Gisgraphy 1.1 and greater.


[top]

spellchecker.activeByDefault=true

Define the default value if the spellchecking parameter is not set. 'true' or 'false' are possible values. this option is case sensitive.
Examples :
spellchecker.activeByDefault=true
spellchecker.activeByDefault=false
The spellchecker is only enabled if the spellchecking parameter AND the spellchecker.enabled are equal to 'true'


[top]

spellchecker.spellcheckerDictionaryName

The name of the SolR spellchecker to use. This option is case sensitive and you must set the same name in the SolRconfig.xml file and in the env.properties in lower case. By default two spellcheckers are defined : 'levenstein' and 'jarowinkler'. In practice jarowinkler seems to give better results.
Examples :
spellchecker.spellcheckerDictionaryName=jarowinkler
spellchecker.spellcheckerDictionaryName=levenstein


[top]

spellchecker.collateResults

For a request with several words, return a string with the best suggestion for each word. For instance, for 'pariss frence' => 'Paris France' will be suggested. This option is case sensitive. 'true' and 'false' are possible values.
Examples :
spellchecker.collateResults=true
spellchecker.collateResults=false


[top]

googleMapAPIKey (deprecated)

The Google maps API key was required in v 3.0 but not in v 4.0 because we now use OpenStreetMap maps.
Examples :
googleMapAPIKey=ABQIAAAAC0kUg2SfDYBO-AEagcTgvhQ5aXWj7Kef4ih_G0qG0UGxHdmrpFrmSD7sGMwTJIN1g7C45waZ5ybiQ


[top]

googleanalytics.uacctcode

The Google analytics code to have statistics
Examples :
googleMapAPIKey=ABQIAAAAC0GGGDYBO-AEagcTgvhQ5aXWj7Kef4ih_G0qG0UGxHdmrpFrmSD7sGMwTJIN1g7C45waZ5ybiQ


[top]

Geocoding service

[top]

Description


The Gisgraphy geocoding service allows you to transform postal addresses or other descriptions (a street, a city, a postal code, a country, or a combination) of a location into a (latitude, longitude) coordinate. The goal is to give a free open-source alternative to Google maps, and nominatim that is not really usable (words should be comma separated, poor relevance,...)
[top]

Output formats and languages

The following languages are supported :
  • XML
  • JSON
  • PHP
  • Ruby
  • Python
  • YAML

[top]

Parameters

  • The address (required) : a postal address, structured or not, a street, a city, a postal code, a country, or a combination.
    Examples :
    • 101 Avenue des Champs-Elysées 75008 Paris
    • Champs elysees paris
    • Champs elysees
    • paris
  • You can also specify a structured address by specifying the separate parts of the address : houseNumber, streetName, streetType, city, state, zipCode, etc. A full list can be found here

  • The country (not required for Gisgraphy v 4.0 and above) : The country where the place/address is. It is used to determine the postal address format and to improve performance. It will probably be optional in next version to ease the usability. The value must be the ISO 3166 Alpha 2 code of the country
    Examples :
    • US
    • FR
    • DE


  • postal : whether the given address is a postal address. default to false. In other words, if the address follow the specification or if it is a well-formed address as it was written on an envelope. This parameter will enable the parsing of the address by the address parser before geocoding, this way, the relevance will be better because because if parsing is successful, we will know the meaning of each word. Note that you can also specify each field if you already know them.
    Examples :
    • true
    • false
    • on


  • The callback method name (optional), use to wrap the content into a (alphanumeric) Javascript method. Works only for script output formats (JSON, PHP, Ruby, Python)
    Examples :
    • executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)

  • The indentation (optional) : indents the results. Default to false. Possible values are true|false (or "on" when used with the rest service. If you use a checkbox in a web form, to indent the results, the value will be "on" or "off", so for a simple use : the value of indent can be "true" or "on".


  • Actually, only XML can be indented. It is not a bug : Indent JSON is possible but decreases performance.

  • the API key (optional) : the API key to use if you use premium webservices this parameter is useless for local installation


[top]

Web service

The geocoding web service uses a servlet to wrap the Java API. It links web parameters to a geocoding query and output the results to an HTTP feed.
It is recommended to explore the API
All the parameters should be case insensitive. If you've got some problems with case, please report a bug.
All the parameters should be encoded in UTF-8 and the URL MUST be encoded.


Here is a summary of the Web parameters mapping :
Parameter descriptionWeb parameter name
addressaddress
A structured addressAny field that can describe an address. a list of fields can be found at here
countrycountry
postalpostal
Callback method namecallback
Output formatformat
Indentindent
apikeyapi key (only for premium webservices, useless for local installation)

Examples :
geocoding/geocode?address=108%20avenue%20des%20champs%20elysees%20paris&countrycode=FR

geocoding/geocode?address=108%20avenue%20des%20champs%20elysees%20paris&countrycode=FR&format=json

/geocoding/geocode?housenumber=105&streetname=avenue des champs elysees&city=paris

By default the geocoding service is mapped to /geocoding pattern but you can change it in the WEB-INF/web.xml



[top]

Output fields description

The Geocoding service returns a list of addresses. It also return the parsed address in a parsedAddress field ()when the address parser is enabled. Here is a description of all the output fields of an address that can be returned :
fielddescriptionExamples of valueExamples in address
houseNumberOfficial number assigned to an address by the municipality, several languages supported3;151-125;eight123 street of Philadelphia city, apt 5A, Washington
houseNumberInfoAll information that give extra information on the house numberbis, ter, quater,125 bis rue de la france 75000 Paris
streetNameThe official name of the street or the ordinal numberMain, 8TH100 MAIN ST POB 1022 SEATTLE WA 98104
streetTypeThe type of the streetstreet,st,bd,dr,bvd,...100 MAIN ST POB 1022 SEATTLE WA 98104
cityThe city or locality, a small town or village name sometimes is included in an address when the Delivery Point is outside the boundary of the main Post Town that serves it.APPLEFORDLeda Engineering Ltd APPLEFORD ABINGDON OX14 4PG
dependentLocality"Sub" city attached to a big cityDublinboulevard of liberty Washington
PostTowna city is a required part of all postal addresses in the United KingdomLondon49 Featherstone Street LONDONEC1Y 8SY
stateThe state or county when applicable, can be fullname or abbreviationWA100 MAIN ST POB 1022 SEATTLE WA 98104
districtThe district, mainly use for RussiaALEKSCEVSKTY (r-n)ul. Lesnaya d. 5 pos. Lesnoe ALEKSCEVSKTY r-n VORONEJSKAYA obl 247112 RUSSIAN FEDERATION
quarterA section of an urban settlementDOĞANBEY MAH(turkey),French QuarterMebusevleri Mah. Önder Cad. Ankara Ap. 11/8 ALEKSCEVSKTY
zipCodeThe zip or post code98104100 MAIN ST POB 1022 SEATTLE WA 98104
extraInfoInformations on floor, unit, and sometimes POBOX,..floor 6,Hangar of the century100 MAIN ST POB 1022 SEATTLE WA 98104
100 MAIN ST 3rd floor SEATTLE WA 98104
POBoxPost office box, Boite postale, Casilla de Correo,..POB 45, POBOX 52,boite postale 89,Casilla de Correo 17100 MAIN ST POB 1022 SEATTLE WA 98104
100 MAIN ST 3rd floor SEATTLE WA 98104
POBoxInfoextra info on post office box, Boite postale, Casilla de Correo,..CEDEX 015, rue Foobar, 75725 Paris CEDEX 01
POBoxAgencyAgency where the office box, Boite postale, Casilla de Correo isKHOURIBGA PRINCIPALEP.O 1737 KHOURIBGA PRINCIPALE 25005 KHOURIBGACEDEX
preDirectionThe cardinal direction before the name of the streetN,NE;NorthN broadway bd
postDirectionThe cardinal direction after the name of the street N,NE;North boulevard of liberty north Washington
streetNameIntersectionThe official name of the intersection streetMainN street of Philadelphia & W boulevard of liberty Washington
streetTypeIntersectionThe type of the intersection streetstreet,st,bd,dr,bvd,...N street of Philadelphia & W boulevard of liberty Washington
preDirectionIntersectionThe cardinal direction before the name of the intersection streetN,NE;NorthN street of Philadelphia & W boulevard of liberty Washington
postDirectionIntersectionThe cardinal direction after the name of the intersection street N,NE;NorthN street of Philadelphia & boulevard of liberty SOUTH Washington
civicNumberSuffixThe number that follows the house number (Canada only)1/210-123 1/2 main street NW MONTREAL QC H3Z 2Y7
floorThe floor in an address, not a floor number in a unit (Brasilia only)8o andarSBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900
sectorThe sector in an address (Brasilia only)SBNSBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900
quadrantThe quadrant in an address (Brasilia only)Quadra 13SBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900
blockThe block in an address (Brasilia only)
the block in austria, singapore,... address
Bloca B
2
SBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900
Rennbahnweg 25/2/15 1220 WIEN
countryThe country nameUSA
United States
France
Paris - France
countrycodeThe countrycode given in the requestFR
US
DE
N/A


[top]

Java API

The geocoding API looks like this
IGeocodingService geocodingService = new GeocodingService();
	String rawAddress = "101 Avenue des Champs-Elysées 75008 Paris";
	AddressQuery query =new AddressQuery("101 Avenue des Champs-Elysées 75008 Paris", "FR");
	AddressResultsDto results =geocodingService.geocode(query);
	/* or 
	Address address=new Address();
	address.setCity("Paris");
	address.setZipCode("75008");
	address.setHouseNumber("101");
	address.setStreetType("Avenue")
	address.setStreetName("des Champs-Elysées");
	AddressResultsDto result = geocodingService.geocode(address,"FR");
	*/
	System.out.println("Query tooks "+result.getQTime()+" ms and"+
		" return "+result.getNumFound()+" result(s)");
	//if the parser is enabled or if the geocoder is called with a structured address
	//then, the the parsedAddress field is filled.
	System.out.println("parsed address : "+result.getParsedAddress());
	for (Address address : results.getResult()){
		System.out.println("housenumber : "+address.getHouseNumber());
		System.out.println("streetType : "+address.getStreetType());
		System.out.println("streetname : "+address.getStreetName());
		System.out.println("PObox : "+address.getPOBox());
		System.out.println("lat : "+address.getlat());
		System.out.println("long : "+address.getLng());
		System.out.println("city : "+address.getCity());
		System.out.println("district : "+address.getDistrict());
		System.out.println("state : "+address.getState());
		//see all fields description above...
		
	}


You can output results to an OutputStream (useful for servlet use) or a String.
The API is thread safe.
It is possible to create a query directly from an HTTP servlet request
[top]

Adress Parser

The International address parser is based on a modular engine, The address-parser is now a spin off and has a dedicated site: http://address-parser.net
You can try it for free
[top]

Reverse geocoding service

[top]

Description


The Reverse geocoding service allows to search for an address for a given GPS position.
[top]

Output formats and languages

The following languages are supported :
  • XML
  • JSON
  • PHP
  • Ruby
  • Python
  • GeoRSS

[top]

Parameters

  • The latitude (north-south) for the location point to search around. The value is a floating number, between -90 and +90. It uses GPS coordinates. This parameter is required.
    Examples :
    • -4.2
    • +4,2

  • The longitude (east-West) for the location point to search around. The value is a floating number between -180 and +180. It uses GPS coordinates. This parameter is required.
    Examples :
    • 3.6
    • 3,6

  • The callback method name (optional), used to wrap the content into a method name, must be alphanumeric and operates only for script output (JSON,PHP,Ruby,Python)
    Examples :
    • executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)

  • The output format (optional) : The formats available are :
    • XML (Default)
    • JSON
    • Python
    • Ruby
    • PHP
    • YAML

  • The indentation (optional) : indents the results. Default to false. Possible values are true|false. If you use a checkbox in a web form to indent the results, the value will be "on" or "off", so for a simple use : the value of indent, for the web service can be "true" or "on".

  • Actually, only XML can be indented. It is not a bug : Indented JSON is possible but decreases performance.



  • the API key (optional) : the API key to use if you use premium webservices this parameter is useless for local installation

[top]

Web service

The reverse geocoding web service uses a servlet to wrap the Java API. It links web parameters to a reverse geocoding query and output the results via HTTP.
It is recommended to explore the API
All the parameters should be case insensitive. if you've got some problems with case, please notify a bug.
All the parameters should be encoded in UTF-8 and the URL MUST be encoded.


Here is a summary of the Web parameters mapping :
Parameter descriptionWeb parameter name
Latitudelat
Longitudelng
Callback method namecallback
Output formatformat
Indentindent
apikeyapi key(only for premium webservices, useless for local installation)

Examples :
http://localhost:8080/reversegeocoding/search?lat=4.5&lng=5.7&format=json&callback=doit&indent=true

http://localhost:8080/reversegeocoding/search?lat=4.5&lng=5.7


[top]

Output fields description

Here is a description of all the output fields, :
FieldDescriptionApplicable for
errorA String only present if an error occurred (e.g : empty Latitude or longitude)When error occurred
numFoundThe number of results to display with this query (actually always 1)
QTimeThe execution time of the query in ms
distanceThe distance between the point and the address found
houseNumberThe house number of the address
nameThe name of the address (could be a shop name, etc.)
streetNameThe name of street of the address (could be a shop name, etc.), it could be null (even if the house number is not), if the name of the street is unknown
cityThe city of the address
citySubdivisiona more precise information than the city (quarter, place,...)
stateThe state of the address
countryCodeThe countrycode of the address
geocodingLevelinformation on how deep the reverse geocoding was able to do (house number, street, city)
latThe latitude of the middle of the street(north-south)
lngThe longitude of the middle of the street(east-west)


[top]

Java API

The geoloc API looks like this
			Point point = GeolocHelper.createPoint(LONGITUDE, LATITUDE);
			Output output = Output.withFormat(OUTPUTFORMAT)
								  .WithIndentation();
			ReverseGeocodingQuery query = new ReverseGeocodingQuery(point, Output.withFormat(OutputFormat.JSON).withIndentation());
    			ReverseGeocodingService service = new ReverseGeocodingService();
    			AddressResultsDto result = service.executeQuery(query);
    			System.out.println("reverse geocoding took "+result.getQTime()+" ms");
    			System.out.println("reverse geocoding find address "+result.getResult()+" ms");
Click on the UPPERCASE parameters above to see the description of the parameter.

The methods are designed with DSL (Domain Specific Language), and can be chained as shown in the example above.


You can output results to an OutputStream (useful for servlet use) or a String.
The API is thread safe.
It is possible to create a query directly from an HTTP servlet request
[top]

Street / tracking service

[top]

Description


The street service allows you to search for street by GPS position.
you can :
The street search service searches for the nearest street based on the shape of the streets, not the middle point. It is recommended to use this service with OpenGTS or Traccar or if you want to search the nearest distance to a street. It is recommended to use the fulltext search engine with placetype=street to search by name, the fulltext engine search around a point, it is more like a restriction and distance is the one to the middle of the street. Street search service is the one to use when GPS is more important than name.

Actually the street search doesn't return house numbers (probably in next version). If you want house numbers you have to use the fulltext service
Gisgraphy is designed to allow search with auto completion / suggestions :
If you don't specify the lat/lng and do a search that 'contains', indexes won't be used, so performance will be poor. With fulltext search performance will be OK.
[top]

Output formats and languages

The following languages are supported :
[top]

Parameters

[top]

Web service

The street/ geocoding web service use a servlet to wrap the Java API. It links web parameters to a street query and output the results via HTTP.
It is recommended to explore the API
All the parameters should be case insensitive. if you've got some problems with case, please notify a bug.
All the parameters should be encoded in UTF-8 and the URL MUST be encoded.


Here is a summary of the Web parameters mapping :
Parameter descriptionWeb parameter name
Latitudelat
Longitudelng
name of the streetname
one way streetoneway
Type of the streetstreettype
Radiusradius
Start pagination indexfrom
End pagination indexto
Callback method namecallback
Output formatformat
Distance field distance
Indentindent
apikeyapi key(only for premium webservices, useless for local installation)

Examples :
http://localhost:8080/street/streetsearch?lat=4.5&lng=5.7&radius=5000&from=1&to=10&format=xml&name=strip&indent=true

http://localhost:8080/street/streetsearch?lat=4.5&lng=5.7



Actually, the webservice limits the number of results to 50, but it can be changed (at compilation time)

[top]

street type

Streets are group by type. Here are the possible values :
note that in v 3.0 the street type were different (they have been updated to reflect the OpenStreetMap evolution):
  • BYWAY
  • MINOR
  • SECONDARY_LINK
  • CONSTRUCTION
  • UNSURFACED
  • BRIDLEWAY
  • PRIMARY_LINK
  • LIVING_STREET
  • TRUNK_LINK
  • STEPS
  • PATH
  • ROAD
  • PEDESTRIAN
  • TRUNK
  • MOTROWAY
  • CYCLEWAY
  • MOTORWAY_LINK
  • PRIMARY
  • FOOTWAY
  • TERTIARY
  • SECONDARY
  • TRACK
  • UNCLASSIFIED
  • SERVICE
  • RESIDENTIAL
[top]

Output fields description

Here is a description of all the output fields, :
FieldDescriptionApplicable for
errorA String only present if an error occurred (e.g : empty Latitude or longitude)When error occurred
numFoundThe number of results display with this query (it takes the pagination into account)
QTimeThe execution time of the query in ms
queryThe name of the street that has been search (aka : name)
distanceThe distance between the point and the nearest point to the street in meters
nameThe name of the street
gidUnique id of the street, it is unique between GeoNames and OpenStreetMap
openstreetmapIdOpenStreetMap unique id of the street
isInInformation on the city where the street is (depends on OpenStreetMap 'is_in' field), the city in general
isInInformation on the city where the street is (depends on OpenStreetMap 'is_in' field), the city in general
isInPlaceInformation on the place where the street is. Often something more precise than the city or municipality
isInAdmInformation on the administrative division where the street is: region, district,...
isInZipInformation on the zip where the street is. only one is output.
lengththe length of the street in meters
streetTypeThe type of the street (see street type list)
oneWayWhether the street is a one way street or not
latThe latitude of the middle of the street(north-south)
lngThe longitude of the middle of the street(east-west)
countryCodeThe ISO 3166 country code


Some fields were not available in older version of Gisgraphy. please see old versions
[top]

Java API

The geoloc API looks like this
			Point point = GeolocHelper.createPoint(LONGITUDE, LATITUDE);
			Pagination pagination = paginate().from(STARTINDEX).to(ENDINDEX);
			Output output = Output.withFormat(OUTPUTFORMAT)
								  .WithIndentation();
			StreetSearchQuery query = new StreetSearchQuery(point,RADIUS,
					pagination,output,STREETTYPE,
					ONEWAY,NAME);
			String results = streetSearchEngine.executeQueryToString(query);
Click on the UPPERCASE parameters above to see the description of the parameter.
Here is an example :
			Point point = GeolocHelper.createPoint(-3.5F, 45F);
			Pagination pagination = paginate().from(1).to(10);
			Output output = Output.withFormat(OutputFormat.XML)
								  .WithIndentation();	
			StreetSearchQuery streetQuery = new StreetSearchQuery((point,100000
				pagination, output, StreetType.PEDESTRIAN,false,"Avenue des c");
			String result = geolocSearchEngine.executeQueryToString(streetQuery);

The methods are designed with DSL (Domain Specific Language), and can be chained as shown in the example above.


You can output results to an OutputStream (useful for servlet use) or a String.
The API is thread safe.
It is possible to create a query directly from an HTTP servlet request
[top]

Fulltext / autocompletion service

[top]

Description


The fulltext service allows you to search for features / places / POIs / cities / zipcodes/ administartion divisions/ street. It allow to do autocompletion / autosuggetion
you can The search is case insensitive, use synonyms (Saint/st, ..), separator characters stripping, ...
[top]

Output formats and languages

The following languages are supported :
[top]

Parameters

[top]

Autocompletion / suggestions

Gisgraphy can provide, via the fulltext search engine, a very powerful auto completion / suggestion engine. combined with the other parameters of the fulltext engine (latitude, longitude, radius, countrycode,...), It allow you to have a very powerful and personalized suggestion engine.
You can :
You can use the Gisgraphy js API to initiate an auto completion input text very simply, or use the Gisgraphy leaflet geocoder plugin to use autocompletion on a map. There is also a reverse geocoding plugin.
Note that adding a Lat/Long and a radius impacts performance because the distance is calculated for all the results, but the relevance will probably be better : the user in 75% of use cases searches for something near them. To do autocompletion, simply add the 'suggest' parameter to true. e.g
/fulltext/suggest?format=json&suggest=true&allwordsrequired=false&style=long&lat=50.4589901&lng=3.2124411&radius=0&placetype=city&placetype=adm&placetype=street&from=1&to=20&q=paris&apikey=12

See the Gisgraphy leaflet plugin for more details.
[top]

Web service

The full text web service use a servlet to wrap the Java API. It links web parameters to a fulltext query and output the results via HTTP.
It is recommended to explore the API
All the parameters should be case insensitive. If you've got some problems with case, please report a bug.
All the parameters should be encoded in UTF-8 and the URL MUST be encoded.

  • the API key (optional) : the API key to use if you use premium webservices this parameter is useless for local installation



  • Here is a summary of the Web parameters mapping :
    Parameter nameWeb parameter namecomment
    The searched textq
    all words requiredallwordsrequired
    Latitudelat
    Longitudelng
    Radiusradius
    suggestsuggest
    Start pagination indexfrom
    End pagination indexto
    Output formatformat
    Language codelang
    Output style verbositystyle
    placetypeplacetypeYou can specify more than one placetype http://localhost:8080/fulltext/fulltextsearch?q=paris&placetype=city&placetype=adm
    country codecountry
    indentindent
    spellcheckingspellchecking
    api keyapi key (only for premium webservices, useless for local installation)

    If you use a checkbox in a form to indent the results, the value will be "on" or "off", so for a simple use : the value of indent, for the fulltext web service can be "true" or "on".
    Examples :
    http://localhost:8080/fulltext/fulltextsearch?q=paris&from=1&to=10&format=xml&lang=fr&style=short&placetype=city&country=fr&indent=true

    http://localhost:8080/fulltext/fulltextsearch?q=paris



    Actually, the webservice limits the number of results to 10.

    By default the fulltext service is mapped to /fulltext pattern but you can change it in the WEB-INF/web.xml



    [top]

    Output fields description

    Here is a description of all the output fields :
    FieldDescriptionAvailable from style
    errorA String only present if an error occurred (e.g : empty query)
    The field 'error' appears in the path response/responseHeader/error
    ERROR
    feature_idA unique id that identify the featureSHORT
    nameThe name of the featureSHORT
    scorea number that indicates the relevance of the resultSHORT
    fully_qualified_nameA name of the form : (adm1Name et adm2Name are printed) Paris, Département de Ville-De-Paris, Ile-De-France, (FR)SHORT
    placetypeThe place Type of the FeatureSHORT
    country_codeThe ISO 3166 country codeSHORT
    country_nameThe name of the country the features belongs toSHORT
    zipcodeThe zipcodesSHORT
    google_map_urlThe URL to get the location on Google MapMEDIUM
    amenityInformations on category of OpenStreetMap POIsMEDIUM
    openstreetmap_map_urlThe URL to get the location on OpenStreetMap.orgMEDIUM
    yahoo_map_urlThe URL to get the location on Yahoo MapMEDIUM
    one_waywhether the street is one way or not (only for placetype street)MEDIUM
    LengthThe length of the street (only for placetype street)MEDIUM
    openstreetmap_idThe OpenStreetMap unique id of the street (only for placetype street)MEDIUM
    is_inInformation on the city where the street / POI is (depends on OpenStreetMap 'is_in' field), the city in general (only for placetype street)MEDIUM
    is_in_placeInformation on the place where the street / POI is (quater, common place). Generally a place at a lower level than cityMEDIUM
    is_in_admInformation of the administration division where the street / POI is.MEDIUM
    is_in_zipInformation of the zipcode where the street / POI is (often fill for placetype street)MEDIUM
    house_numbersa list of all the house numbers and their coordinates (only for placetype street). house number are sortedMEDIUM
    municipalityif the place is a municipality. it is usefull for geonames feature that don't have concept of 'city' but a populated place (that can be a quarter)MEDIUM
    amenityInformations on category of OpenStreetMap POIsMEDIUM
    street_typeThe type of the street (only for placetype street)MEDIUM
    country_flag_urlThe relative URL to get the country flag imageMEDIUM
    feature_classThe feature Class. More...MEDIUM
    feature_codeThe feature Code. More...MEDIUM
    populationHow many people live in this featureMEDIUM
    elevationElevation in metersMEDIUM
    name_asciiThe ASCII nameMEDIUM
    timezoneThe timezone (e.g :Europe/Paris)MEDIUM
    gtopo30Average elevation of 30'x30' (ca 900mx900m) area in metersMEDIUM
    latThe latitude (north-south)MEDIUM
    lngThe longitude (east-West)MEDIUM
    continentThe continent the country belongs (only for country placetype)MEDIUM
    currency_codeThe ISO 4217 Currency from the curencycode (only for country placetype)MEDIUM
    currency_nameThe name of the currency of the country (only for country placetype)MEDIUM
    fips_codeThe FIPS Code of the country (only for country placetype)MEDIUM
    isoalpha2_country_codeThe ISO 3166 alpha 2 code of the country (only for country placetype)MEDIUM
    isoalpha3_country_codeThe ISO 3166 alpha 3 code of the country (only for country placetype)MEDIUM
    postal_code_maskThe mask that postal codes should verify. e.g : ##### (only for country placetype)MEDIUM
    postal_code_regexThe regular expression that postal codes should verify (only for country placetype)MEDIUM
    phone_prefixThe phone prefix of the country. e.g : +33 .(only for country placetype)MEDIUM
    spoken_languagesList of languages spoken in the country (only for country placetype)MEDIUM
    tldTop level domain of the country (only for country placetype)MEDIUM
    capital_nameName of the capital of the country(only for country placetype)MEDIUM
    areaArea of the country in m² (only for country placetype)MEDIUM
    levelLevel of the Adm 1 , 2, 3, or 4(only for Adm placetype)MEDIUM
    adm1_codeThe internal code for the administrative division of level 1LONG
    adm2_codeThe internal code for the administrative division of level 2LONG
    adm3_codeThe internal code for the administrative division of level 3LONG
    adm4_codeThe internal code for the administrative division of level 4LONG
    adm1_nameThe name of the administrative division of level 1LONG
    adm2_nameThe name of the administrative division of level 2LONG
    adm3_nameThe name of the administrative division of level 3LONG
    adm4_nameThe name of the administrative division of level 4LONG
    name_alternateThe alternate names of the feature that without specific language codeLONG
    name_alternate_languagecodeThe alternate names of the feature for this language CodeLONG
    adm1_name_alternateThe alternate names of the administrative division of level 1 without specific language codeFULL
    adm1_name_alternate_languagecodeThe alternatenames of the administrative division of level 1 for this language CodeFULL
    adm2_name_alternateThe alternate names of the administrative division of level 2 without specific language codeFULL
    adm2_name_alternate_languagecodeThe alternatenames of the administrative division of level 2 for this language CodeFULL
    country_name_alternateThe alternate names of the country without specific language codeFULL
    country_name_alternate_languagecodeThe alternate names of the country for this language code
    , If you specify link as a languagecode, you will get the Wikipedia link
    FULL
    fullyQualifiedAddressNOT USED YETN/A



    Some fields were not available in older version of Gisgraphy. Please see old versions


    [top]

    Java API

    The fulltext API looks like this
    			Pagination pagination = paginate().from(STARTINDEX).to(ENDINDEX);
    			Output output = Output.withFormat(OUTPUTFORMAT)
    					.withLanguageCode(LANGUAGECODE).withStyle(VERBOSITY)
    					.WithIndentation();
    					
    			FulltextQuery fulltextQuery = new FulltextQuery("SEARCHEDTEXT",
    					pagination, output, PLACETYPE.class, COUNTRYCODE);
    					fulltextQuery.withAllWordsRequired(true)
    					.around(POINT)
    					.withRadius(RADIUS).limitToCountryCode("FR");
    			String result = fullTextSearchEngine.executeQueryToString(fulltextQuery);
    
    Click on the UPPERCASE parameters above to see the description of the parameter.
    Here is an example :
    			Pagination pagination = paginate().from(1).to(10);
    			Output output = Output.withFormat(OutputFormat.XML)
    					.withLanguageCode("FR").withStyle(OutputStyle.SHORT)
    					.WithIndentation();
    			FulltextQuery fulltextQuery = new FulltextQuery("Paris Texas",
    					pagination, output, new String[]{City.class}, "US")
    					.around(GeolocHelper.createPoint(54.2F, -95F))
    					.withRadius(1000).limitToCountryCode("FR");
    			String result = fullTextSearchEngine.executeQueryToString(fulltextQuery);
    

    You can output results to an OutputStream (useful for servlet use) or a String.
    The API is thread safe.
    It is possible to create a query directly from an HTTP servlet request
    The methods are designed with DSL (Domain Specific Language), and can be chained as shown in the example above.

    [top]

    Geolocalisation service

    [top]

    Description


    The geolocalisation service allows to search for features around a earth location.
    you can
    [top]

    Output formats and languages

    The following languages are supported :
    [top]

    Parameters

    [top]

    Web service

    The geolocalisation web service uses a servlet to wrap the Java API. It links web parameters to a geoloc query and output the results via HTTP.
    It is recommended to explore the API
    All the parameters should be case insensitive. if you've got some problems with case, please report a bug.
    All the parameters should be encoded in UTF-8 and the URL MUST be encoded.


    Here is a summary of the Web parameters mapping :
    Parameter nameWeb parameter name
    Latitudelat
    Longitudelng
    Radiusradius
    Start pagination indexfrom
    End pagination indexto
    Callback method namecallback
    Output formatformat
    Placetypeplacetype
    Distance field distance
    Indentindent
    apikeyapi key (only for premium webservices, useless for local installation)

    Examples :
    http://localhost:8080/geoloc/findnearbylocation?lat=4.5&lng=5.7&radius=5000&from=1&to=10&format=xml&placetype=city&indent=true

    http://localhost:8080/geoloc/findnearbylocation?lat=4.5&lng=5.7



    Actually, the webservice limits the number of results to 10.

    By default the geolocalisation service is mapped to /geoloc pattern but you can change it in the WEB-INF/web.xml



    [top]

    Output fields description

    Here is a description of all the output fields, some fields are specific to certain placetype (e.g : area is only available if the feature is a country) :
    FieldDescriptionApplicable for
    errorA String only present if an error occurred (e.g : empty Latitude or longitude)When error occurred
    numFoundThe number of results display with this query (it takes the pagination into account)All placetype
    QTimeThe execution time of the query in msAll placetype
    distanceThe distance between the point and the gisFeature in metersAll placetype
    nameThe name of the featureAll placetype
    asciiNameThe ASCII name of the featureAll placetype
    feature_idA unique id that identify the featureAll placetype
    openstreetmapIdOpenStreetMap unique id of the featureAll placetypes
    is_inInformation of the city where the street / POI is (depends on openstreetmap 'is_in' field), the city in general (only for placetype street)MEDIUM
    is_in_placeInformation of the place where the street / POI is (quarter, common place). Generally a place at a lower level than cityAll placetype
    is_in_admInformation of the administration division where the street / POI is.All placetype
    is_in_zipInformation of the zipcode where the street / POI is (often fill for placetype street)
    oneWayWhether the street is a one way street or notStreet only
    streetTypethe type of the streetStreet only
    lengthlength of the street in meters Street only
    countryCodeThe ISO 3166 country codeAll placetypes
    openstreetmap_map_urlThe URL to get the location on OpenStreetMap.org(since v3.0 beta3)All placetypes
    google_map_urlThe URL to get the location on Google MapAll placetype
    yahoo_map_urlThe URL to get the location on Yahoo MapAll placetypes
    country_flag_urlThe relative URL to get the country flag imageAll placetypes
    featureClassThe feature Class. More...All placetypes
    featureCodeThe feature Code. More...All placetypes
    placeTypeThe Type of Feature see faqAll placetype
    populationHow many people live in this featureAll placetype
    latThe latitude (north-south)All placetypes
    lngThe longitude (east-West)All placetypes
    adm1CodeThe internal code for the administrative division of level 1All placetypes
    adm2CcodeThe internal code for the administrative division of level 2All placetypes
    adm3CodeThe internal code for the administrative division of level 3All placetypes
    adm4CodeThe internal code for the administrative division of level 4All placetypes
    adm1NameThe name of the administrative division of level 1All placetypes
    adm2NameThe name of the administrative division of level 2All placetypes
    adm3NameThe name of the administrative division of level 3All placetypes
    adm4NameThe name of the administrative division of level 4All placetypes
    timezoneThe time zone (e.g : Europe/Paris)All placetypes
    gtopo30Average elevation of 30'x30' (ca 900mx900m) area in metersAll placetypes
    elevationThe elevation in metersAll placetypes
    zipcodeThe zipcodes (only for city and city subdivision), one node by zipcodeCity,CitySubdivision,
    levelThe level of the Administrative division (1-4)Adm
    areaThe area of the featureCountry
    tldtop-level domain name, (last part of an Internet domain name) of the countryCountry
    capitalNameThe Capital of the countryCountry
    continentThe continent the country belongsCountry
    postalCodeRegexThe regexp that all zipcode/postalcode of the country matchesCountry
    currencyCodeThe Currency code (ISO_4217) of the countryCountry
    currencyNameThe Currency name of the countryCountry
    areaThe area of the countryCountry
    fipsCodeThe FIPS Code of the countryCountry
    equivalentFipsCodeThe FIPS Code of the country when no code are availableCountry
    iso3166Alpha2CodeThe iso 3166 Alpha 2 code of the countryCountry
    iso3166Alpha3CodeThe iso 3166 Alpha 3 code of the countryCountry
    iso3166NumericCodeThe iso 3166 numeric code of the countryCountry
    phonePrefixThe phone prefix of the countryCountry
    postalCodeMaskThe mask that all postal codes of the country matchesCountry


    Some fields were not available in older version of Gisgraphy. please see old versions
    [top]

    Java API

    The geoloc API looks like this
    			Point point = GeolocHelper.createPoint(LONGITUDE, LATITUDE);
    			Pagination pagination = paginate().from(STARTINDEX).to(ENDINDEX);
    			Output output = Output.withFormat(OUTPUTFORMAT)
    								  .WithIndentation();
    			GeolocQuery query = new GeolocQuery(point,RADIUS,pagination,output,PLACETYPE.class);
    			String results = geolocSearchEngine.executeQueryToString(query);
    
    Click on the UPPERCASE parameters above to see the description of the parameter.
    Here is an example :
    			Point point = GeolocHelper.createPoint(-3.5F, 45F);
    			Pagination pagination = paginate().from(1).to(10);
    			Output output = Output.withFormat(OutputFormat.XML)
    								  .WithIndentation();	
    			GeolocQuery geolocQuery = new GeolocQuery(point,100000
    					pagination, output, City.class);
    			String result = geolocSearchEngine.executeQueryToString(geolocQuery);
    

    The methods are designed with DSL (Domain Specific Language), and can be chained as shown in the example above.


    You can output results to an OutputStream (useful for servlet use) or a String.
    The API is thread safe.
    It is possible to create a query directly from an HTTP servlet request
    [top]

    Client libraries

    Client libraries exists in several languages. Consult the client library dedicated page
    [top]

    Admin Interface

    To access the admin interface :
    [top]

    Login - Password

    You can insert the two default users with the provided script in the sql directory : insert_users.sql
    There are two default users already set :
    userpasswordprofileDescription
    useruserROLE_USERuser with simple rights : can not admin other users, can only edit his profile, can not import data
    adminadminROLE_ADMINuser with all rights : can admin other users and profiles, can edit options,can import data.

    It is highly recommended that you change the default users of the admin interface. To do so : login as 'admin' with password 'admin' or edit the 'insert_users.sql' file in the sql directory, set the users / passwords / roles, and run the script

    [top]

    Import data

    To import data, you must log as a user with admin rights. Then go to the Administration menu -> Run importer. A wizard will guide you to choose the correct options.
    The importer process may takes more than 40 hours, depending on how much data you import and the machine the importer runs on. (some dumps are available on the download server)

    [top]

    Add / edit data

    please consult the dedicated documentation on how add/edit features. Note that in versions greater than 3-beta2 you can draw street directly on map.


    If you need you can add / edit / delete entries in the database. you can also edit all the associated fields, (alternatenames and zip codes).

    To do so :

    Then you can add a new street or place, and search for feature to edit. You can also search for place to edit. The interface is the same as the one for fulltext search :
    click on the 'advanced search' link to to get more options

    To delete some entries, search for the place you want to delete, click the 'edit' button and then click on the remove link.

    You can find some screenshots on the screenshots page
    [top]

    Screenshots

    Some screenshots are available here

    [top]

    Security

    [top]

    Default admin password


    It is highly recommended that you change the default users of the admin interface. To do so, login as 'admin' with password 'admin'

    [top]

    Protect WebServices

    Some users wants to restrict the SolR engine to the host 'localhost' in order to disallow users to ask the SolR search engine directly. You can use a firewall and restrict the access of the Webapp with the following code
    With Tomcat :
    <Context path="/path/to/secret_files">
      <Valve className="org.apache.catalina.valves.RemoteAddrValve"
             allow="127.0.0.1" deny=""/>
    </Context>
    


    With Jetty :
    A server configuration-XML-file can look something like this:
    <Configure class="org.mortbay.jetty.Server">
    ...
    <Call name="addContext">
    ...
    <Call name="addHandler">
    <Arg>
    <New class="IPAccessHandler">
    <Set name="Standard">deny</Set>
    <Set name="AllowIP">192.168.0.103</Set>
    <Set name="AllowIP">192.168.0.100</Set>
    </New>
    </Arg>
    </Call>
    


    See more on http://www.jdocs.com/jetty/5.1.11.rc0/org/mortbay/http/handler/IPAccessHandler.html
    [top]

    Performance

    [top]

    Jmeter

    Some Jmeter benchmarks are available (scripts and results) here.
    [top]

    Database Optimisation

    In order to have good performance it is recommended that you use database indexes. As far as I know it is possible to tell Hibernate to create indexes but it is not possible to choose the type of index (BTREE,GIST, and so on) with annotations. You must create your own index with the following code :
    DROP  INDEX IF EXISTS locationindex ;
    
    CREATE INDEX locationindex
      ON gisfeature
      USING gist
      ("location");
    
    VACUUM FULL ANALYZE;
    
    
    

    You can do this for all the tables that have Geometry columns.
    A script named 'createGISTIndex.sql' is provided in the 'SQL' directory in the Gisgraphy distribution to create all the GIST indexes for all the tables.

    You will have GREATER performance if you specify a placetype; if you search for placetype 'gisFeature', your query will be slower.

    You can define the default Geoloc Placetype in the env file (in the Classpath) with the option defaultGeolocSearchPlaceType


    You can use command line but PGAdmin could be a friendly way.

    If you use PostGIS 1.3.1 or greater you don't have to use the GIST indexes because they will automatically be used. More .

    It is recommended to run :
    VACUUM FULL ANALYZE;
    on PostgreS, after an import
    [top]

    JVM optimisations

    You will have better performance if you run Gisgraphy and the SolR server in two distinct JVMs. To run SolR in a separate JVM, copy the SolR Directory (default parameter) with the schema.xml, SolRconfig.xml, the data directory, and so on to a SolR distribution and start it with java -jar start.jar (or an other way of your choice, that's the easy way). Then you can remove the SolR.war from the Gisgraphy release and configure the fulltextsearch URL to point to the new SolR URL. It is also recommended to use the Sun JVM (not the GCJ one) and to use the VMargs -server

    To have great performance we recommend that you use the Sun -jdk version 6.0.

    Other tips

    We strongly recommend that you install Gisgraphy (using SolR) on a Linux or Unix OS. Due to a JVM bug and other reasons, Windows users will get less performance than Unix users. If you want to tune performance you should call the /SolR/admin/stats.jsp page and watch the cache section. hitRatio, eviction and warmupTime values can be useful. Read the SolR Caching Wiki page for more information.
    The /SolR/admin/luke page can also give you interesting information (if index is optimized,...)