Gisgraphy user guide


To suggest a change or a correction to any part of the documentation, please send a mail to David Masclet.

Introduction
About
version
technical informations...
What's gisgraphy for ?
Some examples of uses
Requirements
What technologies are used ?
Placetype schema
License
Installation
Import Data
Options and environement specific settings
Import failure
Street geocoding service
Description
Parameters
Web service
Output fields description
Java API
Full text service
Description
Parameters
Web service
Output fields description
Java API
Geolocalisation service
Description
Parameters
Web service
Output fields description
Java API
Client libraries
Python
Java
PHP
RUBY
Admin Interface
Login - Password
Import data
Screenshots
Security
Default admin password
Protect webServices
Performance
Jmeter
Database optimisations
JVM optimisations
[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 and api docs for older versions here
[top]

About

Gisgraphy is a free and open source framework. Gisgraphy goal is to provide tools to use free GIS Data on the Web. Actually it manage Geonames and OpenStreetMap (42 million entries). it provides an importer to inject the data into a strongly typed Postgres / Postgis database and use them via webservices : worldwide geocoding, worldwide reverse geocoding, fulltext and find nearby. Results can be output in XML, Atom, RSS, JSON, PHP, Ruby, and Python. Here are the main functionalities :
[top]

Technical informations...

[top]

What's Gisgraphy for ?

[top]

Some examples of uses

[top]

Requirements

[top]

What technologies are used ?

[top]

Placetype schema

Here is a simple diagramme that represents relation beetween the placetype, gisFeature, Adm, country, and languages.



GisFeature is the mother class of all the placetype, it has all the basic informations.
Language represents a spoken language
AlternateName is a specific name for a specific language.

All the placetype extends gisFeature. Such as :
Adm are in tree structure.

A GisFeature :
[top]

License

Gisgraphy is licensed under the terms of the LGPL V3.0 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 (Geoloc and fulltext) is a servlet. Each servlet can be run in debug Mode. The error message will be in verbose mode. To do so just declare the servlet init parameter "debugMode" to true (in the web.xml) as shown :
	<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 $GISGRAPHYDISTRIBUTION/webapps/ROOTWEB-INF/classes directory of the Gisgraphy distribution
Take care of white spaces in properties file : MyProperties=bar is not the same as MyProperties= bar (whitespace 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 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 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.geonames.enabled

Wether the importers related to Geonames will be processed. If 'true' the importer will be done. 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 importer will be done. This option should be in lower case
Examples :
importer.openstreetmap.enabled=true
importer.openstreetmap.enabled=false


Don't forget the ending slash (or backslash if you use windows) !


[top]

importer.geonames.downloadURL

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


Don't forget the ending slash for the URL !


[top]

importer.openstreetmap.downloadURL

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


Don't forget the ending slash for the URL !


[top]

importer.geonamesfilesToDownload

This option determines the files to be download from the importer.geonames.downloadURL URL. The files must be ';' separated. You can specify any files, but if you download from the Geonames server, you should specify country ZIP files (or allcountries.zip) and alternateNames.zip . This option is case sensitive.
Examples :
importer.importer.geonamesfilesToDownload=AD.zip;CY.zip
importer.importer.geonamesfilesToDownload=allCountries.zip


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

this option has been renamed from importer.filesToDownload to importer.geonamesfilesToDownload in order to specify a different url for openstreet map (importer.openstreetmapfilesToDownload)

It is not necessary To download CountryInfo.txt,iso-languagecodes.txt, because there are already in the Gisgraphy distrib. Just focus on the country you want to process and alternatenames.zip if you want to import alternate names.

If allCountries.txt file is in the importer.geonames.dir Directory, the other countries files will be logically ignored.


[top]

importer.openstreetmapfilesToDownload

This option determines the files to be download from the importer.openStreetMap.downloadURL URL. The files must be ';' separated. You can specify any files, but if you download from the Gisgraphy server, you should specify country ZIP files (or allcountries.zip) and alternateNames.zip . This option is case sensitive.
Examples :
importer.openstreetmapfilesToDownload=AD.zip;CY.zip
importer.openstreetmapfilesToDownload=allCountries.zip



[top]

importer.retrieveFiles

Wether the files defined by the importer.filesToDownload option should be downloaded. If 'true' the importer will download the files according to the importer.filesToDownload option. If 'false', it will use the files already presents in importer.geonames.dir. 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 we should throws an exception and stop the import if a line in an imported file haven't the expected number of fields (CSV fields). This option should be in lower case. it is recommended to set it to false in a standard import. if you use Gisgraphy for errors correction, set it to true.
Even if you want to do errors correction, and set it to false, you can see the reported errors in log files and fix them at the end of the import. It can be easier to fix all the errors in one time.


Examples :
importerConfig.wrongNumberOfFieldsThrows=true
importerConfig.wrongNumberOfFieldsThrows=false


[top]

importerConfig.missingRequiredFieldThrows

Wether we should throws an exception and stop the import of data if a required field is missing. This option should be in lower case. It is recommended to set it to false in a standard import. If you use Gisgraphy for errors correction, set it to true.
Even if you want to do errors correction, and set it to false, you can see the reported errors in log files and fix them at the end of the import. It can be easier to fix all the errors in one time.


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. imported (Administrative division and country).
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
P[.]PPL[A-Z&&[^QW]];P[.]PPL$;P[.]STLMT$;V.FRST. : import Israeli settlements and all the cities except destroyed and abandoned city, and the forests


See http://download.geonames.org/export/dump/featureCodes.txt to have a full description of feature class / code or see what are the "feature codes" used in GeoNames ?


[top]

importerConfig.tryToDetectAdmIfNotFound

If this option is set to 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.
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...
and 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 the Adm1, Adm2, Adm3 and Adm4 files. This option tells what to do if an AdmX file (determines with the importerConfig.admXFileName option) is already present 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.countriesFileName (version >= 2.0 beta2)
[top]

importerConfig.alternateNamesFileName

Specify the filename of the CSV file with 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

Some of the alternate names are provided in each country dump file and all the alternate names with languages and additionnal information are in a separated file name. The alternate names provided in the country files are incomplete. if you want to import the alternate names of the country files (faster but a lot of informations are lost) 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. 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
Examples :
geolocsearch.defaultGeolocSearchPlaceType=City
geolocsearch.defaultGeolocSearchPlaceType=
This name of the class should not ends with '.class' but is case sensitive.


[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 only available from gisgraphy 1.1.


[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. it must match the name in the solrconfig.xml file. This option is case sensitive and you must set the 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 give better results.
Examples :
spellchecker.spellcheckerDictionaryName=jarowinkler
spellchecker.spellcheckerDictionaryName=levenstein


[top]

spellchecker.collateResults

For a request with several word, 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. it is required if you want to use Google maps features (see the result of a geocoding search for example). 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 (see more on the Google analytics page)
Examples :
googleMapAPIKey=ABQIAAAAC0GGGDYBO-AEagcTgvhQ5aXWj7Kef4ih_G0qG0UGxHdmrpFrmSD7sGMwTJIN1g7C45waZ5ybiQ


[top]

spellchecker.collateResults

For a request with several word, 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]

Import failure

When an error occured during import. You have to:
Never re-run an import before cleaning the database and restart the web application, it will failed!!.

[top]

street / geocoding service

[top]

Description


The street / geocoding service allows to search for street around earth location.
you can : the service is design to allow search with autosuggestion and autocompletion
[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
search modemode
one way streetoneway
Type of the streetstreettype
Radiusradius
Start pagination indexfrom
End pagination indexto
Output formatformat
Distance field distance
Indentindent

Examples :
http://localhost:8080/street/streetsearch?lat=4.5&lng=5.7&radius=5000&from=1&to=10&format=xml&name=strip&mode=fulltext&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)

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



[top]

street type

type are group by type. here is a list of type a street can have :
[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
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 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.
you can The search is case insensitive, use synonyms (Saint/st, ..), separator characters stripping, ...
[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.


Here is a summary of the Web parameters mapping :
Parameter nameWeb parameter name
The searched textq
Start pagination indexfrom
End pagination indexto
Output formatformat
Language codelang
Output style verbositystyle
placetypeplacetype
country codecountry
indentindent
spellcheckingspellchecking

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
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);
			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, 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 in the example above.

[top]

Geolocalisation service

[top]

Description


The geolocalisation service allows to search for features around earth location.
you can
[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
Output formatformat
Placetypeplacetype
Distance field distance
Indentindent

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

[top]

Python

You can find the python client here
[top]

Java

Not done yet, if you wish to contribute, please send a mail
[top]

PHP

Not done yet, if you wish to contribute, please send a mail
[top]

Ruby

Not done yet, if you wish to contribute, please send a mail
[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 and check the configuration. Click on the 'Run importer' link. a page with the import status will be display and refresh every minuts.
The importer process may takes more than 24 hours, depending on how much data you import and the machine the importer runs on. (some dumps will be soon availables)
because The admin inteface is based on Appfuse : If you have some questions about basic features of the admin interface, see Appfuse documentation
[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