/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)
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\\
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\\
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\\
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
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
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.
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 !
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 !
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 !
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.
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
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
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/
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
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
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
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
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 :
- If
importerConfig.syncAdmCodesWithLinkedAdmOnes
is set to 'true' then the admXcodes and admXnames of the features will be the same as the linked Adm One (in our example : if importerConfig.tryToDetectAdmIfNotFound
is set to 'true' the adm1Code will be 'A1' and the Adm2Code will be 'B2' that's to say the same as the Adm ones)
- If
importerConfig.syncAdmCodesWithLinkedAdmOnes
is set to 'false', the admXcodes and admXnames of the features will be the same as the CSV file (in our example : if importerConfig.tryToDetectAdmIfNotFound
is set to 'true', the adm1Code will be 'A3' and the Adm2Code will be 'B2' And the Linked Adm will be null)
In other words if you want the importer to set the admXcode and admXnames 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
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 :
- skip : extraction will be skiped, and the existing file will be used
- backup : The already existing file will be backup (with the date and the current time), a new file will be extracted and used
- reprocess : the file will be replace by the new one
Examples :
importerConfig.adm3ExtracterStrategyIfAlreadyExists=reprocess
importerConfig.adm4ExtracterStrategyIfAlreadyExists=skip
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
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
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
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
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
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)
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.
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.
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.
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
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
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
fulltextsearch.maxConnectionsPerHost
Limits the numbers of connections to the SolR server per host. Recommended : 32.
fulltextsearch.maxTotalConnections
Limits the numbers of connections to the SolR server for all hosts. Recommended : 128.
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=
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?
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.
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.
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
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.
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
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
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
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
googleanalytics.uacctcode
The Google analytics code to have statistics
Examples :
googleMapAPIKey=ABQIAAAAC0GGGDYBO-AEagcTgvhQ5aXWj7Kef4ih_G0qG0UGxHdmrpFrmSD7sGMwTJIN1g7C45waZ5ybiQ
Geocoding service
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,...
Output formats and languages
The following languages are supported :
- XML
- Json
- Php
- Ruby
- Python
- YAML
Parameters
- The address (required) : can be a postal address, a street, a city, a postal code, a country, or a combination.
Examples :
- 101 Avenue des Champs-Elysées 75008 Paris
- Champs elysees paris
- Champs elysees
- paris
- The country (required) : The country where the Place/address is. it is used to determine the postal address format and to improve performance. it will probably be optionnal in next version to ease the usability. The value must be the ISO 3166 Alpha 2 code of the country
Examples :
- The postal : whether the given address is a postal address. default to false. In other words, if the address follow the specifications or if it is a well formed address as it was writen on an envelop.
this parameter will enable the parsing of the address by the address parser before geocoding, this way, the relevance will be better because we will know the meaning of each word.
Examples :
- The callback method name (optional), use to wrap the content into a (alphanumeric) javascript method. operate only for script output formats (json, PHP, Ruby, Python)
Examples :
- executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)
- The indentation (optional) : indents the results. Default to false. Possible values are true|false (or "on" when used with the rest service. If you use a checkbox in a web form, to indent the results, the value will be "on" or "off", so for a simple use : the value of indent, for can be "true" or "on".
Actually, only XML can be indented. It is not a bug : Indent JSON is possible but decrease performance.
- the apikey (optional) : the apikey to use if you use premium webservices this parameter is useless for local installation
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 description | Web parameter name |
address | address |
country | country |
postal | postal |
Callback method name | callback |
Output format | format |
Indent | indent |
apikey | apikey (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
Output fields description
Here is a description of all the output fields of an adress that can be returned :
field | description | Examples of value | Examples in address |
houseNumber | Official number assigned to an address by the municipality, several languages supported | 3;151-125;eight | 123 street of philadelphia city, apt 5A, Washington |
houseNumberInfo | All informations that give extra informations on the house number | bis, ter, quater, | 125 bis rue de la france 75000 Paris |
streetName | The official name of the street or the ordinal number | Main, 8TH | 100 MAIN ST POB 1022 SEATTLE WA 98104 |
streetType | The type of the street | street,st,bd,dr,bvd,... | 100 MAIN ST POB 1022 SEATTLE WA 98104 |
city | The 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. | APPLEFORD | Leda Engineering Ltd APPLEFORD ABINGDON OX14 4PG |
dependentLocality | "Sub" city attached to a big city | Dublin | boulevard of liberty Washington |
PostTown | a city it is required part of all postal addresses in the United Kingdom | London | 49 Featherstone Street LONDONEC1Y 8SY |
state | The state or county when applicable, can be fullName or abbreviation | WA | 100 MAIN ST POB 1022 SEATTLE WA 98104 |
district | The district, mainly use for russia | ALEKSCEVSKTY (r-n) | ul. Lesnaya d. 5 pos. Lesnoe ALEKSCEVSKTY r-n VORONEJSKAYA obl 247112 RUSSIAN FEDERATION |
quarter | A section of an urban settlement | DOĞANBEY MAH(turkey),French Quarter | Mebusevleri Mah.
Önder Cad. Ankara Ap. 11/8 ALEKSCEVSKTY |
zipCode | The zip or post code | 98104 | 100 MAIN ST POB 1022 SEATTLE WA 98104 |
extraInfo | Informations on floor, unit, and sometimes POBOX,.. | floor 6,Hangar of the century | 100 MAIN ST POB 1022 SEATTLE WA 98104 100 MAIN ST 3rd floor SEATTLE WA 98104 |
POBox | Post office box, Boite postale, Casilla de Correo,.. | POB 45, POBOX 52,boite postale 89,Casilla de Correo 17 | 100 MAIN ST POB 1022 SEATTLE WA 98104 100 MAIN ST 3rd floor SEATTLE WA 98104 |
POBoxInfo | extra info on Post office box, Boite postale, Casilla de Correo,.. | CEDEX 01 | 5, rue Foobar, 75725 Paris CEDEX 01 |
POBoxAgency | Agency where the office box, Boite postale, Casilla de Correo is | KHOURIBGA PRINCIPALE | P.O 1737 KHOURIBGA PRINCIPALE 25005 KHOURIBGACEDEX |
preDirection | The cardinal direction before the name of the street | N,NE;North | N broadway bd |
postDirection | The cardinal direction after the name of the street | N,NE;North | boulevard of liberty north Washington |
streetNameIntersection | The official name of the intersection street | Main | N street of philadelhia & W boulevard of liberty Washington |
streetTypeIntersection | The type of the intersection street | street,st,bd,dr,bvd,... | N street of philadelhia & W boulevard of liberty Washington |
preDirectionIntersection | The cardinal direction before the name of the intersection street | N,NE;North | N street of philadelhia & W boulevard of liberty Washington |
postDirectionIntersection | The cardinal direction after the name of the intersection street | N,NE;North | N street of philadelhia & boulevard of liberty SOUTH Washington |
civicNumberSuffix | The number that follow the house number (Canada only) | 1/2 | 10-123 1/2 main street NW MONTREAL QC H3Z 2Y7 |
floor | The floor in an address, not a floor number in a unit (Brasilia only) | 8o andar | SBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900 |
sector | The sector in an address (Brasilia only) | SBN | SBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900 |
quadrant | The quadrant in an address (Brasilia only) | Quadra 13 | SBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900 |
block | The 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 |
country | The country name | USA United States France
| Paris - France |
countrycode | The countrycode given in the request | FR US DE
| N/A |
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
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
Reverse geocoding / street service
Description
The Reverse geocoding / street service allows to search for street by name or GPS position (or both).
you can :
- Specify GPS position
- Give the begining or a part of the name of the street (useful for autocompletion)
- Limit search to a specific type (e.g : Pedestrian, highway, residential, ... 25 type availables)
- Limit search to a specified radius
- Limit search to one way streets
- Paginate the results
- Tells if you want the output to be indented (currently, apply only for XML, not json for performance reasons. may change in next version)
Gisgraphy is designed to allow search with auto suggestion and auto completion :
- To search for streets by entire name use the fulltext search (you can also specify GPS coordinate, and change the 'allwords required' option to esae the search).
- To do auto completion use the street webservice
- To do auto suggestion use SOLR directly (see this article in french, or use google to translate in english, i will soon add some code in the developper zone)
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.
Output formats and languages
The following languages are supported :
- XML
- Json
- Php
- Ruby
- Python
- Georss
- ATOM
- YAML
Parameters
- The latitude (north-south) for the location point to search around. The value is a float, between -90 and +90. It use GPS coordinates. could be optional but need to be valid if specified
Examples :
- The longitude (east-West) for the location point to search around. The value is a float between -180 and +180. It use GPS coordinates. could be optional but need to be valid if specified
Examples :
- A part of the name of the street (optional) or the name of the street : limit the search to the street that starts/contains with the specified name (WITHOUT STREET NUMBER). You could put the name and the type of the street. Example : 'Boulevard Paul'.the search is case insensitive.
The search mode is deprecated in V3.0 The fulltext mode has been removed in gisgraphy v3.0 (default is always contains) and is replaced by the fulltext search with placetype="street". The results and accuracy is really better but you can not specify oneway or streettype parameter parameter or get the distance anymore. if you really need this features, please
send a mail
IMPORTANT TIPS : If you need to do a fulltext search and you don't care about distance, oneway or streettype, use the fulltext search engine with placetype=street. you will get best accuracy and performance
- The radius (optional) : distance from the location point in meters we'd like to search around. The value is a number > 0 if it is not specify or incorrect : The default value will be used (10 km).
Examples :
- oneway : whether the street should be a oneWay street (optional) : limit the search to the street that are one way street
- Start pagination index (optional) : The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1.
- End pagination Index (optional) : The last pagination index. if < 1 or not specified, it will be set to startindex + 50.
- The callback method name (optional), use to wrap the content into a method name, must be alphanumeric and operate only for script outputformat (json,php,ruby,python)
Examples :
- executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)
- The output format (optional) : The formats available are :
- Distance field : Wether (or not) we want the distance field to be output. This option is usefull to improve the performances if we don't care about the distance (e.g : we search for name). Of course, the results won't be sorted by distance. If you use a checkbox in a form to indent the results, the value will be "on" or "off", so to simplify the use : the value for the web service can be "true" or "on".
- The indentation (optional) : indents the results. Default to false. Possible values are true|false. If you use a checkbox in a web form to indent the results, the value will be "on" or "off", so for a simple use : the value of indent, for the web service can be "true" or "on".
Actually, only XML can be indented. It is not a bug : Indent JSON is possible but decrease performance. If it is a critical need you can see an example of how indent json in source code of streetSearchEngine.
- the apikey (optional) : the apikey to use if you use premium webservices this parameter is useless for local installation
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 description | Web parameter name |
Latitude | lat |
Longitude | lng |
name of the street | name |
one way street | oneway |
Type of the street | streettype |
Radius | radius |
Start pagination index | from |
End pagination index | to |
Callback method name | callback |
Output format | format |
Distance field | distance |
Indent | indent |
apikey | apikey(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)
street type
Streets are group by type. Here are the possible values :
- BYWAY
- MINOR
- SECONDARY_LINK
- CONSTRUCTION
- UNSURFACED
- BRIDLEWAY
- PRIMARY_LINK
- LIVING_STREET
- TRUNK_LINK
- STEPS
- PATH
- ROAD
- PEDESTRIAN
- TRUNK
- MOTROWAY
- CYCLEWAY
- MOTORWAY_LINK
- PRIMARY
- FOOTWAY
- TERTIARY
- SECONDARY
- TRACK
- UNCLASSIFIED
- SERVICE
- RESIDENTIAL
Output fields description
Here is a description of all the output fields, :
Field | Description | Applicable for |
error | A String only present if an error occured (e.g : empty Latitude or longitude) | When error occured |
numFound | The number of results display with this query (it takes the pagination into account) | |
QTime | The execution time of the query in ms | |
query | The name of the street that has been search (aka : name) | |
distance | The distance beetween the point and the nearest point to the street in meters | |
name | The name of the feature | |
gid | Unique id of the street, it is unique between geonames and openstreetmap | |
openstreetmapId | openstreetmap unique id of the street | |
isIn | Information of the city where the street is (depends on openstreetmap 'is_in' field), the city in general | |
streetType | The type of the street (see street type list) | |
oneWay | Whether the street is a one way street or not | |
lat | The latitude of the middle of the street(north-south) | |
lng | The longitude of the middle of the street(east-west) | |
countryCode | The ISO 3166 country code | |
Some fields were not available in older version of gisgraphy. please see
old versions
Java API
The geoloc API looks like this
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
Full text service
Description
The full text service allows to search for features / places / street.
you can
- Specify one or more words
- Search for text or zip code
- Specify a GPS restriction
- Limit the results to a specific
- Paginate the results
- Specify the ouput verbosity
- Tells if you want the output to be indented
- Tells that all words are required or not
The search is case insensitive, use synonyms (Saint/st, ..), separator characters stripping, ...
Output formats and languages
The following languages are supported :
- XML
- Json
- Php
- Ruby
- Python
- Georss
- ATOM
Parameters
- The searched text (required) : The text for the query, it can be a zip code, a String or one or more String.
Examples :
- All words required (optional): Wether the fulltext engine should considers all the words specified as required. Default to true. possible values are true|false (or "on" when used with the rest service)
- Start pagination index (optional) : The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1.
- End pagination Index (optional) : The last pagination index. if < 1 or not specified, it will be set to startindex + 10.
- The output format (optional) : The formats available are :
- XML (Default)
- PHP
- JSON
- PYTHON
- RUBY
- ATOM
- GEORSS
- The language code (optional) : The iso 639 Alpha2 or alpha3 Language Code.
Some properties as the AlternateName AdmNames and countryname belongs to a certain language code, The language parameter can limits the output of those fields to a certain language (it only apply when style parameter='style') :
- If the language code does not exists or is not specified, properties with all the languages are retrieved
- If it exists, the properties with the specified language code, are retrieved
Use the alpha2 code when possible, only use the alpha3 code when no alpha2 code exists for the language.
- The output style verbosity (optional) : Determines the output verbosity. 4 styles are available :
- Short : feature_id, name, fully_qualified_name, zipcode (if city or city subdivision), placetype, country_code, country_name
- Medium (default) : Short + lat, lon,street_type(if street),one_way(if street),length(if street), feature_class, feature_code, population, fips,
- Medium (if country) continent, currency_code, currency_name, fips_code, isoalpha2_country_code, isoalpha3_country_code, postal_code_mask, postal_code_regex,
phone_prefix, spoken_languages, tld, capital_name, area
- Medium (adm only) level
- Long : Medium + adm1_name, adm2_name, adm3_name, Adm4_name, adm1_code, Adm2_code, Adm3_code, Adm4_code
- Full : Long + alternateNames, country_alternate_name, adm1_alternate_name, adm2_alternate_name. If the language parameter is specified : only alternate names with the specified language are retrive, otherwise, all the alternate names for all the languages are retrieve
For a full list and descrition of output fields : see
bellow.
- The placetype(s) (optional) : limit the search to the one or more place type. place type regroups some feature class and feature code. You need to specify the class coresponding to the place type you want to search. default : search for all features
See a full list and explanation of placetype :
here.
- The country code (optional) : limit the search to the specify ISO 3166 country code. Default : search in all countries
- The indentation (optional) : indents the results. Default to false. Possible values are true|false (or "on" when used with the rest service see more) Georss and Atom won't be indented for performance reasons
- The spellchecking (optional) : whether some suggestions should be provided if no results are found. default value is the value of the '
spellchecker.activeByDefault
' option (see more).
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 name | Web parameter name | comment |
The searched text | q | |
all words required | allwordsrequired | |
Start pagination index | from | |
End pagination index | to | |
Output format | format | |
Language code | lang | |
Output style verbosity | style | |
placetype | placetype | You can specify more than one placetype http://localhost:8080/fulltext/fulltextsearch?q=paris&placetype=city&placetype=adm |
country code | country | |
indent | indent | |
spellchecking | spellchecking | |
apikey | apikey (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
Output fields description
Here is a description of all the output fields :
Field | Description | Available from style |
error | A String only present if an error occured (e.g : empty query) The field 'error' appears in the path response/responseHeader/error | ERROR |
feature_id | A unique id that identify the feature | SHORT |
name | The name of the feature | SHORT |
fully_qualified_name | A name of the form : (adm1Name et adm2Name are printed) Paris, Département de Ville-De-Paris, Ile-De-France, (FR) | SHORT |
placetype | The place Type of the Feature | SHORT |
country_code | The ISO 3166 country code | SHORT |
country_name | The name of the country the features belongs to | SHORT |
zipcode | The zipcodes | SHORT |
google_map_url | The URL to get the location on Google Map | MEDIUM |
yahoo_map_url | The URL to get the location on Yahoo Map | MEDIUM |
one_way | whether the street is one way or not (only for placetype street) | MEDIUM |
Length | The length of the street (only for placetype street) | MEDIUM |
openstreetmap_id | The openstreetmap unique id of the street (only for placetype street) | MEDIUM |
is_in | Information of the city where the street is (depends on openstreetmap 'is_in' field), the city in general (only for placetype street) | MEDIUM |
street_type | The type of the street (only for placetype street) | MEDIUM |
country_flag_url | The relative URL to get the country flag image | MEDIUM |
feature_class | The feature Class. More... | MEDIUM |
feature_code | The feature Code. More... | MEDIUM |
population | How many people lives in this feature | MEDIUM |
elevation | Elevation in meters | MEDIUM |
name_ascii | The ascii name | MEDIUM |
timezone | The timezone (e.g :Europe/Paris) | MEDIUM |
gtopo30 | Average elevation of 30'x30' (ca 900mx900m) area in meters | MEDIUM |
lat | The latitude (north-south) | MEDIUM |
lng | The longitude (east-West) | MEDIUM |
continent | The continent the country belongs (only for country placetype) | MEDIUM |
currency_code | The ISO 4217 Currency from the curencycode (only for country placetype) | MEDIUM |
currency_name | The name of the curency of the country (only for country placetype) | MEDIUM |
fips_code | The FIPS Code of the country (only for country placetype) | MEDIUM |
isoalpha2_country_code | The ISO 3166 alpha 2 code of the country (only for country placetype) | MEDIUM |
isoalpha3_country_code | The ISO 3166 alpha 3 code of the country (only for country placetype) | MEDIUM |
postal_code_mask | The mask that postal codes should verify. e.g : ##### (only for country placetype) | MEDIUM |
postal_code_regex | The regular expression that postal codes should verify (only for country placetype) | MEDIUM |
phone_prefix | The phone prefix of the country. e.g : +33 .(only for country placetype) | MEDIUM |
spoken_languages | Liste of languages spoken in the country (only for country placetype) | MEDIUM |
tld | Top level domain of the country (only for country placetype) | MEDIUM |
capital_name | Name of the capital of the country(only for country placetype) | MEDIUM |
area | Area of the country in m² (only for country placetype) | MEDIUM |
level | Level of the Adm 1 , 2, 3, or 4(only for Adm placetype) | MEDIUM |
adm1_code | The internal code for the administrative division of level 1 | LONG |
adm2_code | The internal code for the administrative division of level 2 | LONG |
adm3_code | The internal code for the administrative division of level 3 | LONG |
adm4_code | The internal code for the administrative division of level 4 | LONG |
adm1_name | The name of the administrative division of level 1 | LONG |
adm2_name | The name of the administrative division of level 2 | LONG |
adm3_name | The name of the administrative division of level 3 | LONG |
adm4_name | The name of the administrative division of level 4 | LONG |
name_alternate | The alternate names of the feature that without specific language code | LONG |
name_alternate_languagecode | The alternate names of the feature for this language Code | LONG |
adm1_name_alternate | The alternate names of the administrative division of level 1 without specific language code | FULL |
adm1_name_alternate_languagecode | The alternatenames of the administrative division of level 1 for this language Code | FULL |
adm2_name_alternate | The alternate names of the administrative division of level 2 without specific language code | FULL |
adm2_name_alternate_languagecode | The alternatenames of the administrative division of level 2 for this language Code | FULL |
adm3_name_alternate | The alternate names of the administrative division of level 3 without specific language code | FULL |
adm3_name_alternate_languagecode | The alternatenames of the administrative division of level 3 for this language Code | FULL |
adm4_name_alternate | The alternate names of the administrative division of level 4 without specific language code | FULL |
adm4_name_alternate_languagecode | The alternatenames of the administrative division of level 4 for this language Code | FULL |
country_name_alternate | The alternate names of the country without specific language code | FULL |
country_name_alternate_languagecode | The alternate names of the country for this language Code | FULL |
Some fields were not available in older version of gisgraphy. please see
old versions
Java API
The fulltext API looks like this
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.
Geolocalisation service
Description
The geolocalisation service allows to search for features around earth location.
you can
- Specify GPS position
- Limit the results to a specific place type (e.g : search all monuments around a point)
- Limit the results to a specified radius
- Paginate the results
- Tells if you want the output to be indented (currently, apply only for XML, not json for performance reasons. may change in next version)
Output formats and languages
The following languages are supported :
- XML
- Json
- Php
- Ruby
- Python
- Georss
- ATOM
- YAML
Parameters
- The latitude (required) (north-south) for the location point to search around. The value is a float and can be negative. It use GPS coordinates.
Examples :
- The longitude (required) (east-West) for the location point to search around. The value is a float and can be negative. It use GPS coordinates.
Examples :
- The radius (optional) : distance from the location point in meters we'd like to search around. The value is a number > 0 if it is not specify or incorrect : The default value will be used (10 km).
Examples :
- Start pagination index (optional) : The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1.
- End pagination Index (optional) : The last pagination index. if < 1 or not specified, it will be set to startindex + 10.
- The callback method name (optional), use to wrap the content into a method name, must be alphanumeric and operate only for script outputformat (json,php,ruby,python)
Examples :
- executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)
- The output format (optional) : The formats available are :
- XML (Default)
- JSON
- Python
- Ruby
- PHP
- ATOM
- GEORSS
- YAML
- The placetype (optional) : limit the search to the specified place type. place type regroup some feature class and feature code. you need to specify the class coresponding to the place type you want to search. default : search for all features
For performance reasons, it is highly recommended to specify a placetype (if you use web GUI, put a required parameter with the placetype)
See a full list and explanation of placetype :
here.
- Distance field : Wether (or not) we want the distance field to be filled. this option is usefull when we don't care about the distance, to improve the performances. Off course, the results won't be sorted by distance. 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 for the web service can be "true" or "on".
- The indentation (optional) : indents the results. Default to false. Possible values are true|false. 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 geoloc web service can be "true" or "on".
Actually, only XML can be indented. It is not a bug : Indent JSON is possible but decrease performance.
- the apikey (optional) : the apikey to use if you use premium webservices this parameter is useless for local installation
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 name | Web parameter name |
Latitude | lat |
Longitude | lng |
Radius | radius |
Start pagination index | from |
End pagination index | to |
Callback method name | callback |
Output format | format |
Placetype | placetype |
Distance field | distance |
Indent | indent |
apikey | apikey (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
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) :
Field | Description | Applicable for |
error | A String only present if an error occured (e.g : empty Latitude or longitude) | When error occured |
numFound | The number of results display with this query (it takes the pagination into account) | All placetype |
QTime | The execution time of the query in ms | All placetype |
distance | The distance beetween the point and the gisFeature in meters | All placetype |
name | The name of the feature | All placetype |
asciiName | The ASCII name of the feature | All placetype |
feature_id | A unique id that identify the feature | All placetype |
countryCode | The ISO 3166 country code | All placetype |
google_map_url | The URL to get the location on Google Map | All placetype |
country_flag_url | The relative URL to get the country flag image | All placetype |
yahoo_map_url | The URL to get the location on Yahoo Map | All placetype |
featureClass | The feature Class. More... | All placetype |
featureCode | The feature Code. More... | All placetype |
placeType | The Type of Feature see faq | All placetype |
population | How many people lives in this feature | All placetype |
lat | The latitude (north-south) | All placetype |
lng | The longitude (east-West) | All placetype |
adm1Code | The internal code for the administrative division of level 1 | All placetype |
adm2Ccode | The internal code for the administrative division of level 2 | All placetype |
adm3Code | The internal code for the administrative division of level 3 | All placetype |
adm4Code | The internal code for the administrative division of level 4 | All placetype |
adm1Name | The name of the administrative division of level 1 | All placetype |
adm2Name | The name of the administrative division of level 2 | All placetype |
adm3Name | The name of the administrative division of level 3 | All placetype |
adm4Name | The name of the administrative division of level 4 | All placetype |
timezone | The time zone (e.g : Europe/Paris) | All placetype |
gtopo30 | Average elevation of 30'x30' (ca 900mx900m) area in meters | All placetype |
elevation | The elevation in meters | All placetype |
zipcode | The zipcodes (only for city and city subdivision), one node by zipcode | City,CitySubdivision, |
level | The level of the Administrative division (1-4) | Adm |
area | The area of the country | Country |
tld | top-level domain name, (last part of an Internet domain name) of the country | Country |
capitalName | The Capital of the country | Country |
continent | The continent the country belongs | Country |
postalCodeRegex | The regexp that all zipcode/postalcode of the country matches | Country |
currencyCode | The Currency code (ISO_4217) of the country | Country |
currencyName | The Currency name of the country | Country |
area | The area of the country | Country |
fipsCode | The fips Code of the country | Country |
equivalentFipsCode | The fips Code of the country when no code are available | Country |
iso3166Alpha2Code | The iso 3166 Alpha 2 code of the country | Country |
iso3166Alpha3Code | The iso 3166 Alpha 3 code of the country | Country |
phonePrefix | The phone prefix of the country | Country |
postalCodeMask | The mask that all postal code of the country matches | Country |
Some fields were not available in older version of gisgraphy. please see
old versions
Java API
The geoloc API looks like this
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
Client libraries
Client librairies exists in several language. Consult the client librairy dedicated page
Admin Interface
To access the admin interface :
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 :
user | password | profile | Description |
user | user | ROLE_USER | user with simple rights : can not admin other users, can only edit his profile, can not import data |
admin | admin | ROLE_ADMIN | user 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
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)
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 :
- Log into the admin interface with an admin user (default : admin/admin).
- Go to the 'Administration' menu and choose 'Add/edit/delete data'
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 :
- Enter the name (openstreetmapid or gisfeatureid are possible)
- Click the search button
- In the results list, an 'edit' button appears, click on it to get the web form to edit the features or streets
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
Screenshots
some screenshots are available here
Security
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'
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
Performance
Jmeter
Some Jmeter benchs are available (scripts and results) here.
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 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
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,...)