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 content :
Introduction
About
version
Technical informations...
Quick start
Requirements
Which technologies are used ?
License
Installation
Import Data
Options and environement specific settings
Geocoding service
Description
Output formats and languages
Parameters
Web service
Output fields description
Java API
AdressParser
Reverse geocoding / street service
Description
Output formats and languages
Parameters
Web service
Output fields description
Java API
Full text service
Description
Output formats and languages
Parameters
Web service
Output fields description
Java API
Geolocalisation service
Description
Output formats and languages
Parameters
Web service
Output fields description
Java API
Client libraries
Python
Java
PHP
RUBY
Admin Interface
Login - Password
Import data
Add / Edit data
Screenshots
Security
Default admin password
Protect webServices
Performance
Jmeter
Database optimisations
JVM optimisations
Other tips
[top]

Introduction

[top]

version

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

About

Gisgraphy is a free, open source framework that offers the possibility 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 (Geonames and OpenStreetMap : 42 million entries). You can also add your own data with the Web interface or the importer connectors provided. Gisgraphy is production ready, and has been designed to be scalable(load balanced), performant 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 System (OpenGTS) also includes a gisgraphy client...read more Here are the main functionalities :
[top]

Technical informations...

Please consult the developer guide
[top]

Quick start

Please consult the last quick start guide.
[top]

Requirements

[top]

Which technologies are used ?

[top]

License

The Gisgraphy project (www.gisgraphy.com) is a free open sources project under the LGPL license V3. Geonames data are 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 informations
[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 environement specific settings

All the options and environement 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 accounts)
[top]

importer.geonames.dir

This option determines the directory where the Geonames files are located. It must ends 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 bellow. 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 underlaying 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 ends 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 bellow. 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 underlaying 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.geoname.zipcode.dir

This option determines the directory where the Geonames zipcode files are located. It must ends 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 bellow . 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 underlaying file system is case sensitive (e.g : Linux / Unix).
Examples on Linux :
mporter.geoname.zipcode.dir=./data/prod/
mporter.geoname.zipcode.dir=/home/user/data/prod/

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


[top]

importer.geonames.enabled

Wether 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

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


[top]

importerConfig.openstreetmap.fill.isin.field

Wether we search for the nearest city in geonames data to fill the is_in field. This increase the time of the importer but strongly increase 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.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.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.geonamesfilesToDownload

This option determines the files to be download 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 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 re-run the import. If you don't : the files you've downloaded for the first importwill be processed.

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


[top]

importer.openstreetmapfilesToDownload

This option determines the files to be download from the importer.openStreetMap.downloadURL URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip) and alternateNames.zip. This option is case sensitive. If 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.retrieveFiles

Wether the files defined by the importer.*filesToDownload options should be downloaded. If 'true' the importer will download the files. If 'false', it will use the files already presents. 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

Wether the importer should throws an exception and stop the import if a line in an imported CSV file haven't the expected number of fields. This option should be in lower case. Recommended to false, set it to true if you use Gisgraphy for errors correction.
Examples :
importerConfig.wrongNumberOfFieldsThrows=true
importerConfig.wrongNumberOfFieldsThrows=false


[top]

importerConfig.missingRequiredFieldThrows

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


[top]

importerConfig.acceptRegExString

List of regular expresions separated by ';' that determines the feature class / code to be imported. The default value is .* (all the feature class / code), if the value is not specified. The regular expressions must match featureClass.featureCode. The gisFeature which matches "A.ADM." (administrative divisions) and "A.PCL." (countries) regex are automaticaly imported. This option is case sensitive and the should be set in upper case because feature class / code are in upper case.
Examples :
.* : import all gisfeatures, no matter their feature class / code
P[.]PPL[A-Z&&[^QW]];P[.]PPL$;P[.]STLMT$ : import Israeli settlements and all the cities except destroyed and abandoned city
V.FRST. : import all the forests


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


[top]

importerConfig.tryToDetectAdmIfNotFound

If this option is set to (recomended 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 activate errors correction. If set to false, errors 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, put a warning message in 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 little thing 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 too.
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 to choose beetween two strategy : In other words if you want the importer to set the admXcode and admXnames with 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 extract Adm1, Adm2, Adm3 and Adm4 into separate files. This option tells what to do if an AdmX file (determines with the importerConfig.admXFileName option) already exists in the importer.geonames.dir.This option is case sensitive. 3 options are available :
Examples :
importerConfig.adm3ExtracterStrategyIfAlreadyExists=reprocess
importerConfig.adm4ExtracterStrategyIfAlreadyExists=skip


[top]

importerConfig.adm1FileName

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

[top]

importerConfig.adm2FileName

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

[top]

importerConfig.adm3FileName

Specify 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 underlaying file system is case sensitive

[top]

importerConfig.adm4FileName

Specify 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 underlaying file system is case sensitive

[top]

importerConfig.languageFileName

Specify the filename of the CSV file with languages. should normally be 'iso-languagecodes.txt'. This option is case sensitive if the underlaying file system is case sensitive

[top]

importerConfig.countriesInfosFileName

Specify the filename of the CSV file with countries informations. Should normally be 'countryInfo.txt'. This option is case sensitive if the underlaying 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

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

[top]

importerConfig.alternateNameFeaturesFileName

Specify 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 underlaying file system is case sensitive.

[top]

importerConfig.alternateNameAdm1FileName

Specify 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 underlaying file system is case sensitive.

[top]

importerConfig.alternateNameAdm2FileName

Specify 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 underlaying file system is case sensitive

[top]

importerConfig.alternateNameCountryFileName

Specify 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 underlaying file system is case sensitive

[top]

importerConfig.importGisFeatureEmbededAlternateNames

The alternate names are provided in each country dump file, some additionnal information (languages, isPrefered name,...)are in a separated file name. 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. and the placeType must be in the entity package. searching for all placetype decrease performance if there is a lot of feature in the database. This 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 buy premium webservices). This must be a valid URL
Examples :
addressParser.url=http://addressparser.appspot.com/webaddressparser
addressParser.url=http://services.gisgraphy.com/addressparser/parse?
[top]

useAddressParserWhenGeocoding

The option below enable/disable the parsing of the text to geocode. It can improve the response time because no request 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 enable 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 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 put your own implementation
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 equals 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 spellchecker are define : '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 suggest. This option is case sensitive. 'true' and 'false' are possible values.
Examples :
spellchecker.collateResults=true
spellchecker.collateResults=false


[top]

googleMapAPIKey

The google maps api key. Required if you want to use Google maps to display gisgraphy search results in the demo pages. in any case Gisgraphy use google to do search!. See more on the Google Maps page to sign up.
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 to transform street address or other description (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 opensource 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 :
[top]

Parameters

[top]

Web service

The geolocoding web service use a servlet to wrap the Java API. It links web parameters to a geocoding query and output the results to HTTP feed.
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
addressaddress
countrycountry
postalpostal
Callback method namecallback
Output formatformat
Indentindent
apikeyapikey (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&outputformat=json


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

Here is a description of all the output fields of an adress 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 informations that give extra informations 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 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 it is 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 philadelhia & W boulevard of liberty Washington
streetTypeIntersectionThe type of the intersection streetstreet,st,bd,dr,bvd,...N street of philadelhia & W boulevard of liberty Washington
preDirectionIntersectionThe cardinal direction before the name of the intersection streetN,NE;NorthN street of philadelhia & W boulevard of liberty Washington
postDirectionIntersectionThe cardinal direction after the name of the intersection street N,NE;NorthN street of philadelhia & boulevard of liberty SOUTH Washington
civicNumberSuffixThe number that follow 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)");
	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 a HTTP servlet request
[top]

Adress Parser

The International address parser is based on a modular engine, where each country has a list of syntax. So we can add a new country or add a new syntax for a country very simply. some librairies and dictionary make the engine very customisable and give the ability to work quickly. The address Parser has its own documentation page
[top]

Reverse geocoding / street service

[top]

Description


The Reverse geocoding / street service allows to search for street by name or GPS position (or both).
you can : Gisgraphy is designed to allow search with auto suggestion and auto completion :
If you don't specify the lat/lng and do a search that 'contains', indexes won't be used, so performances will be poor. With fulltext search performances 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.
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
apikeyapikey(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 :
[top]

Output fields description

Here is a description of all the output fields, :
FieldDescriptionApplicable for
errorA String only present if an error occured (e.g : empty Latitude or longitude)When error occured
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 beetween the point and the nearest point to the street in meters
nameThe name of the feature
gidUnique id of the street, it is unique between geonames and openstreetmap
openstreetmapIdopenstreetmap unique id of the street
isInInformation of the city where the street is (depends on openstreetmap 'is_in' field), the city in general
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 a HTTP servlet request
[top]

Full text service

[top]

Description


The full text service allows to search for features / places / street.
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]

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.
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.

  • the apikey (optional) : the apikey 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
    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
    apikeyapikey (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 occured (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
    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
    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 of the city where the street is (depends on openstreetmap 'is_in' field), the city in general (only for placetype street)MEDIUM
    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 lives 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 curency 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_languagesListe 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
    adm3_name_alternateThe alternate names of the administrative division of level 3 without specific language codeFULL
    adm3_name_alternate_languagecodeThe alternatenames of the administrative division of level 3 for this language CodeFULL
    adm4_name_alternateThe alternate names of the administrative division of level 4 without specific language codeFULL
    adm4_name_alternate_languagecodeThe alternatenames of the administrative division of level 4 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 CodeFULL


    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);
    			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");
    			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 a 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 earth location.
    you can
    [top]

    Output formats and languages

    The following languages are supported :
    [top]

    Parameters

    [top]

    Web service

    The geolocalisation web service use a servlet to wrap the Java API. It links web parameters to a geoloc query and output the results via HTTP.
    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 nameWeb parameter name
    Latitudelat
    Longitudelng
    Radiusradius
    Start pagination indexfrom
    End pagination indexto
    Callback method namecallback
    Output formatformat
    Placetypeplacetype
    Distance field distance
    Indentindent
    apikeyapikey (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 occured (e.g : empty Latitude or longitude)When error occured
    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 beetween 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
    countryCodeThe ISO 3166 country codeAll placetype
    google_map_urlThe URL to get the location on Google MapAll placetype
    country_flag_urlThe relative URL to get the country flag imageAll placetype
    yahoo_map_urlThe URL to get the location on Yahoo MapAll placetype
    featureClassThe feature Class. More...All placetype
    featureCodeThe feature Code. More...All placetype
    placeTypeThe Type of Feature see faqAll placetype
    populationHow many people lives in this featureAll placetype
    latThe latitude (north-south)All placetype
    lngThe longitude (east-West)All placetype
    adm1CodeThe internal code for the administrative division of level 1All placetype
    adm2CcodeThe internal code for the administrative division of level 2All placetype
    adm3CodeThe internal code for the administrative division of level 3All placetype
    adm4CodeThe internal code for the administrative division of level 4All placetype
    adm1NameThe name of the administrative division of level 1All placetype
    adm2NameThe name of the administrative division of level 2All placetype
    adm3NameThe name of the administrative division of level 3All placetype
    adm4NameThe name of the administrative division of level 4All placetype
    timezoneThe time zone (e.g : Europe/Paris)All placetype
    gtopo30Average elevation of 30'x30' (ca 900mx900m) area in metersAll placetype
    elevationThe elevation in metersAll placetype
    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 countryCountry
    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
    phonePrefixThe phone prefix of the countryCountry
    postalCodeMaskThe mask that all postal code 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 a HTTP servlet request
    [top]

    Client libraries

    Client librairies exists in several language. Consult the client librairy 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 is 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 to change the default users of the admin interface. To do so : You must 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 With 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 availables on the download server)

    [top]

    Add / edit data

    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 to change the default users of the admin interface. To do so : You must 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 user 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 benchs are available (scripts and results) here.
    [top]

    Database optimisations

    in order to have good performances it is recommended to use database indexes. as far as I know it is possible to tell Hibernate to create index but not possible to choose the type of index (BTREE,GIST, and so on) with annotations. so 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 proceed for all the tables which have Geometry collumns.
    A script named 'createGISTIndex.sql' is provided in the 'SQL' dir in the Gisgraphy distribution to create all the GIST indexes for all the tables

    You will have GREATER performnance 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 performances if you run Gisgraphy and the SolR server in two distinct JVM. To run solr in a separated 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 easier 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 recommand to use the sun-jdk in version 6.0

    Other tips

    We strongly recommand to install Gisgraphy (that use SolR) on Linux or Unix Os. Due to JVM bug and other reasons, Windows users will get less performances. if you want to tune performance you should call the /solr/admin/stats.jsp page and watch at cache section. hitRatio, eviction and warmupTime values can be useful. Read the SolR caching wiki page for more informations.
    The /solr/admin/luke page can give you interesting information (if index is optimized,...)