/webapps/ROOTWEB-INF/classes directory
Take care of white spaces in properties file : MyProperties=bar is not the same as MyProperties= bar (whitespaces after the equals sign are taken into account)
importer.geonames.dir
This option determines the directory where the GeoNames files are located. It must end with / or \ according to the operating system path separator. It is also the directory where the GeoNames files will be downloaded from the importer.geonames.downloadURL
URL
. On Windows, the '\' character must be escaped as in the example below. The path can be absolute or relative (from the directory where you've launch Gisgraphy). It is not recommended to put space in the path.
. This option is case sensitive if the underlying file system is case sensitive (e.g : Linux / Unix).
Examples on Linux :
importer.geonames.dir=./data/prod/
importer.geonames.dir=/home/user/data/prod/
Example on Windows
importer.geonames.dir=.\\data\\prod\\
importer.openstreetmap.dir
This option determines the directory where the OpenStreetMap files are located. It must end with / or \ according to the operating system path separator. It is also the directory where the OpenStreetMap files will be downloaded from the importer.openstreetmap.downloadURL
URL
. On Windows The '\' character must be escaped as in the example below. The path can be absolute or relative (from the directory where you've launch Gisgraphy). It is not recommended to put space in the path.
. This option is case sensitive if the underlying file system is case sensitive (e.g : Linux / Unix).
Examples on Linux :
importer.openstreetmap.dir=./data/prod/
importer.openstreetmap.dir=/home/user/data/prod/
Example on Windows
importer.openstreetmap.dir=.\\data\\prod\\
importer.geonames.zipcode.dir
This option determines the directory where the GeoNames zipcode files are located. It must end with / or \ according to the operating system path separator. It is also the directory where the GeoNames zipcode files will be downloaded from the importer.geonames.zip.downloadURL
URL
. On Windows The '\' character must be escaped as in the example below . The path can be absolute or relative (from the directory where you've launch Gisgraphy). It is not recommended to put space in the path.
. This option is case sensitive if the underlying file system is case sensitive (e.g : Linux / Unix).
Examples on Linux :
mporter.geonames.zipcode.dir=./data/prod/
mporter.geonames.zipcode.dir=/home/user/data/prod/
Example on Windows
mporter.geonames.zipcode.dir=.\\data\\prod\\
importer.geonames.enabled
Whether the importers related to GeoNames will be processed (it enable the zipcode importer too). If 'true' the importers will be executed. This option should be in lower case.
Examples :
importer.geonames.enabled=true
importer.geonames.enabled=false
importer.openstreetmap.enabled
Whether the importers related to OpenStreetMap will be processed. If 'true' the importers will be executed. This option should be in lower case.
Examples :
importer.openstreetmap.enabled=true
importer.openstreetmap.enabled=false
importer.openstreetmap.housenumber.enabled
Whether the importers related to house numbers OpenStreetMap will be processed. If 'true' the importers will be executed. This option should be in lower case.
Examples :
importer.openstreetmap.housenumber.enabled=true
importer.openstreetmap.housenumber.enabled=false
importer.quattroshapes.enabled
Whether the importers related to Quattroshapes will be processed. If 'true' the importers will be executed. This option should be in lower case.
Examples :
importer.quattroshapes.enabled=true
importer.quattroshapes.enabled=false
importerConfig.openstreetmap.fill.isin.field
Whether we search for the nearest city in GeoNames data to fill the is_in field. This will increase the run time of the importer but strongly increases the relevance of the geocoder. Default to true.
This option should be in lower case.
Examples :
importerConfig.openstreetmap.fill.isin.field=true
importerConfig.openstreetmap.fill.isin.field=false
DON'T MODIFY this option after importer is done.
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.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.openstreetmap.housenumbers.downloadURL
This option determines the URL of the server to download the house numbers OpenStreetMap files to be processed (typically, the Gisgraphy download server). This option is case sensitive.
Example :
importer.openstreetmap.downloadURL=http://download.gisgraphy.com/openstreetmap/housenumbers/
Don't forget the ending slash !
importer.openstreetmap.cities.downloadURL
This option determines the URL of the server to download the cities OpenStreetMap files to be processed (typically, the Gisgraphy download server). This option is case sensitive.
Example :
importer.openstreetmap.cities.downloadURL=http://download.gisgraphy.com/openstreetmap/cities/
Don't forget the ending slash !
importer.openstreetmap.pois.downloadURL
This option determines the URL of the server to download the POIs (point of interest) OpenStreetMap files to be processed (typically, the Gisgraphy download server). This option is case sensitive.
Example :
importer.openstreetmap.pois.downloadURL=http://download.gisgraphy.com/openstreetmap/pois/
Don't forget the ending slash !
importer.quattroshapes.downloadURL
This option determines the URL of the server to download the Quattroshapes files to be processed (typically, the Gisgraphy download server). This option is case sensitive.
Example :
importer.quattroshapes.downloadURL=http://download.gisgraphy.com/quattroshapes/
Don't forget the ending slash !
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.geonamesfilesToDownload
This option determines the files to be downloaded from the importer.geonames.downloadURL
URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip) and alternateNames.zip. This option is case sensitive. If the allCountries.txt file is in the importer.geonames.dir
directory, the other country files will be logically ignored.
Examples :
importer.geonamesfilesToDownload=US.zip;MX.zip
importer.geonamesfilesToDownload=allCountries.zip
If you run an import, change the option and re-run an import : you must first delete the old downloaded file before you re-run the import. If you don't : the files you've downloaded for the first import will be processed.
It is not necessary to download CountryInfo.txt, iso-languagecodes.txt, because they are already in the gisgraphy data directory of the Gisgraphy distrib.
importer.openstreetmapfilesToDownload
This option determines the files to be downloaded from the importer.openStreetMap.downloadURL
URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip). This option is case sensitive. If the allCountries.txt file is in the importer.geonames.dir
directory, the other countries files will be logically ignored.
Examples :
importer.openstreetmapfilesToDownload=AD.gis;CY.gis
importer.openstreetmapfilesToDownload=allCountries.zip
importer.openstreetmapHouseNumberFilesToDownload
This option determines the house numbers files to be downloaded from the importer.openstreetmap.housenumbers.downloadURL
URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip). This option is case sensitive. If the allCountries.txt file is in the importer.openstreetmap.housenumbers.dir
directory, the other countries files will be logically ignored.
Examples :
importer.openstreetmapHouseNumberFilesToDownload=AD.gis;CY.gis
importer.openstreetmapHouseNumberFilesToDownload=allCountries.zip
importer.openStreetMapCitiesFilesToDownload
This option determines the OpenStreetMap cities files to be downloaded from the importer.openstreetmap.cities.downloadURL
URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip). This option is case sensitive. If the allCountries.txt file is in the importer.openStreetMapCitiesFilesToDownload
directory, the other countries files will be logically ignored.
Examples :
importer.openStreetMapCitiesFilesToDownload=AD.gis;CY.gis
importer.openStreetMapCitiesFilesToDownload=allCountries.zip
importer.openStreetMapPoisFilesToDownload
This option determines the POIs (point of interest) numbers files to be downloaded from the importer.openstreetmap.pois.downloadURL
URL. The files must be ';' separated. Add specific country zip files (or allcountries.zip). This option is case sensitive. If the allCountries.txt file is in the importer.openstreetmap.pois.dir
directory, the other countries files will be logically ignored.
Examples :
importer.openStreetMapPoisFilesToDownload=AD.gis;CY.gis
importer.openStreetMapPoisFilesToDownload=allCountries.zip
importer.quattroshapesFilesToDownload
This option determines the Quattroshapes files to be downloaded from the importer.quattroshapes.downloadURL
URL. The files must be ';' separated. typically the file is shapes.gis. This option is case sensitive. Files will be downloaded in importer.quattroshapes.dir
directory.
Examples :
importer.quattroshapesFilesToDownload=shapes.gis
importer.retrieveFiles
Whether the files defined by the importer.*filesToDownload
option should be downloaded. If 'true' the importer will download the files. If 'false', it will use the files already present. This option should be in lower case.
Examples :
importer.retrieveFiles=true
importer.retrieveFiles=false
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
Whether the importer should throw an exception and stop the import if a line in an imported CSV file doesn't have the expected number of fields. This option should be in lower case. Recommended to be set to false; set it to true if you use Gisgraphy for error correction.
Examples :
importerConfig.wrongNumberOfFieldsThrows=true
importerConfig.wrongNumberOfFieldsThrows=false
importerConfig.missingRequiredFieldThrows
Whether we should throw an exception and stop the import if a required field is missing. This option should be in lower case. Recommended to be set to false, set it to true if you use Gisgraphy for error correction.
Examples :
importerConfig.missingRequiredFieldThrows=true
importerConfig.missingRequiredFieldThrows=false
importerConfig.acceptRegExString
A regular expression for the place type we want to import. The default value is .* (all the place types) if the value is not specified.
Administrative divisions and countries are automatically imported. This option is case insensitive. Place types are the name of the entities class (see package com.gisgraphy.domain.geoloc.entity source code for details) - don't forget to add GISFEATURE for POIs that are not categorized.
Examples :
.*
: import all gisfeatures, no matter their feature class / code
RESTAURANT|BAR
: import all Restaurants and Bars
RESTAURANT|BAR|GISFEATURE
: import all Restaurants and Bars and POI that have no real categories
FOREST
: import all the forests
importerConfig.tryToDetectAdmIfNotFound
If this option is set to (recommended value) true : The importer will try to detect Adm for features if the AdmXcodes values does not correspond to a known Adm. Set this option to true to activate error correction. If set to false, error correction is disabled and if no Adm is found for the AdmXcode, the feature will be linked to a null Adm.
This option is case sensitive and must be set in lower case.
Example : There is an adm with level 2 which have adm1Code = 'A1' and adm2Code = 'B2' in the datastore. Suppose there is a gisFeature which have Adm1code='A3' and Adm2Code='B2', Gisgraphy will detect an error because there is no Adm with those codes. So if this option is set to true, Gisgraphy will correct the error and will link the feature to the Adm with codes adm1Code = 'A1' and adm2Code = 'B2'. If if this option is set to false, Gisgraphy won't try to correct the error, puts a warning message in the logs, and links the feature to a null Adm. This option should be in lower case.
Examples :
importerConfig.tryToDetectAdmIfNotFound=true
importerConfig.tryToDetectAdmIfNotFound=false
importerConfig.syncAdmCodesWithLinkedAdmOnes
This option is a little bit difficult to understand. An example is often simpler than a big speech ;). First, there is a few things you need to know : a feature has the following properties:
FeatureId......Adm...Adm1Code...Adm2Code...Adm3Code...Adm4Code...adm1Name...Adm2Name...adm3Name...Adm4Name...
An Adm is a feature too and has the same properties.
So, a feature is linked to an administrative division (AKA : Adm). For performance reasons, the codes and names of the Adms are stored in the Feature itself.
Now consider the example above : if there is an error the adm will not be the same as the codes in the CSV files. This option allow you to choose between two strategies :
- If
importerConfig.syncAdmCodesWithLinkedAdmOnes
is set to 'true', then the admXcodes and admXnames of the features will be the same as the linked Adm One (in our example : if importerConfig.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 to the CSV one : set this option to false. if you want those codes to be the same as the linked Adm : set it to true.
If you don't know what to do : set it to the recommended value : true. This option is case sensitive and must be set in lower case.
importerConfig.tryToDetectAdmIfNotFound and importerConfig.syncAdmCodesWithLinkedAdmOnes are orthogonal concepts
importerConfig.admXExtracterStrategyIfAlreadyExists
In order to import the Adm before the other features, Gisgraphy extracts Adm1, Adm2, Adm3 and Adm4 into separate files. This option tells Gisgraphy what to do if an AdmX file (determined with the importerConfig.admXFileName
option) already exists in the importer.geonames.dir
. This option is case sensitive. 3 options are available :
- skip : extraction will be skipped, and the existing file will be used;
- backup : The already existing file will be backed up (with the date and the current time) and a new file will be extracted and used;
- reprocess : the file will be replaced by the new one
Examples :
importerConfig.adm3ExtracterStrategyIfAlreadyExists=reprocess
importerConfig.adm4ExtracterStrategyIfAlreadyExists=skip
importerConfig.adm1FileName
Specifies the filename of the CSV file with Administrative division with level 1. Should normally be 'admin1Codes.txt'. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.adm2FileName
Specifies the filename of the CSV file with Administrative division with level 2. Should normally be 'admin2Codes.txt'. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.adm3FileName
Specifies the filename of the CSV file with Administrative division with level 3. Should normally be 'admin3Codes.txt'. This file name will be used to extract Adm with level 3. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.adm4FileName
Specifies the filename of the CSV file with Administrative division with level 4. Should normally be 'admin4Codes.txt'. This file name will be used to extract Adm with level 4. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.languageFileName
Specifies the filename of the CSV file with languages. Should normally be 'iso-languagecodes.txt'. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.countriesInfosFileName
Specifies the filename of the CSV file with country information. Should normally be 'countryInfo.txt'. This option is case sensitive if the underlying file system is case sensitive. This option is not the list of countries to import.
To be clearer the option importerConfig.countriesFileName has been renamed to 'importerConfig.countriesInfosFileName' (version >= 2.0)
importerConfig.alternateNamesFileName
Specifies the filename of the CSV file that contains alternate names. Should normally be 'alternateNames.txt'. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.alternateNameFeaturesFileName
Specifies the name of the file where the alternate names of features that are not adm1, adm2, or country are (extracted). Should normally be 'alternateNames-features.txt'. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.alternateNameAdm1FileName
Specifies the the name of the file where the alternate names of adm with level 1 are (extracted). Should normally be 'alternateNames-adm1.txt'. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.alternateNameAdm2FileName
Specifies the the name of the file where the alternate names of adm with level 2 are (extracted). Should normally be 'alternateNames-adm2.txt'. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.alternateNameCountryFileName
Specifies the name of the file where the alternate names of countries are. Should normally be 'alternateNames-country.txt'. This option is case sensitive if the underlying file system is case sensitive.
importerConfig.importGisFeatureEmbededAlternateNames
The alternate names are provided in each country dump file, some additional information (languages, isPrefered name,...) are in a separate file. If you want to import the alternate names of the country files (faster but you miss some informations and the language parameter of the fulltext service won't be taken into account) set this option to true - in that case the importerConfig.alternateNamesFileName will be ignored. If you want a full import with the alternatenames separated file set this option to false. This option is case sensitive and must be set in lowercase.
Examples :
importerConfig.importGisFeatureEmbededAlternateNames=true
importerConfig.importGisFeatureEmbededAlternateNames=false
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. The placeType must be in the entity package. Searching for all placetypes decreases performance if there are a lot of feature in the database. The name of the class should not ends with '.class' and is case sensitive.
Examples :
geolocsearch.defaultGeolocSearchPlaceType=City
geolocsearch.defaultGeolocSearchPlaceType=
addressParser.url
The url of the address parser server. This option is the one to change when you buy premium webservices. This must be a valid URL
Examples :
addressParser.url=http://services.gisgraphy.com/addressparser/parse?
useAddressParserWhenGeocoding
The option below enables/disables the parsing of the text to geocode. It can improve the response time because no requests are done to Gisgraphy (offline mode)
. Case sensitive, should be in lowercase true|false, default to false.
Examples :
useAddressParserWhenGeocoding=true
useAddressParserWhenGeocoding=false
Note that address parser will be enabled if this option is true OR if the
postal parameter is true. so you can disable the address parser by default and enable it at query time.
searchForExactMatchWhenGeocoding
Whether we should do a search with all words required AND a search without. It decrease the response time but can be useful if you want to search for common places (hotel, city, adm, monument) AND address.
It allow you to do a fulltext search and a geocoding request.
Default to true. Set to false if you only want to geocode
#address, not place (better performance, less accuracy). Case sensitive, should be in lowercase true|false.
Examples :
searchForExactMatchWhenGeocoding=true
searchForExactMatchWhenGeocoding=false
Two versions are deployed : one on Gisgraphy server and one on Google appengine.
addressParser.class
The (Java) class of the address parser client. This option can be changed to fit your own implementation. This parameter is useful when you buy a license of the parser and use it internally (without the webservices)
Examples :
addressParser.class=com.gisgraphy.addressparser.AddressParserClient
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 spellcheckers are defined : '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 suggested. This option is case sensitive. 'true' and 'false' are possible values.
Examples :
spellchecker.collateResults=true
spellchecker.collateResults=false
googleMapAPIKey (deprecated)
The Google maps API key was required in v 3.0 but not in v 4.0 because we now use OpenStreetMap maps.
Examples :
googleMapAPIKey=ABQIAAAAC0kUg2SfDYBO-AEagcTgvhQ5aXWj7Kef4ih_G0qG0UGxHdmrpFrmSD7sGMwTJIN1g7C45waZ5ybiQ
googleanalytics.uacctcode
The Google analytics code to have statistics
Examples :
googleMapAPIKey=ABQIAAAAC0GGGDYBO-AEagcTgvhQ5aXWj7Kef4ih_G0qG0UGxHdmrpFrmSD7sGMwTJIN1g7C45waZ5ybiQ
Geocoding service
Description
The Gisgraphy geocoding service allows you to transform postal addresses or other descriptions (a street, a city, a postal code, a country, or a combination) of a location into a (latitude, longitude) coordinate. The goal is to give a free open-source alternative to Google maps, and nominatim that is not really usable (words should be comma separated, poor relevance,...)
Output formats and languages
The following languages are supported :
- XML
- JSON
- PHP
- Ruby
- Python
- YAML
Parameters
- The address (required) : a postal address, structured or not, a street, a city, a postal code, a country, or a combination.
Examples :
- 101 Avenue des Champs-Elysées 75008 Paris
- Champs elysees paris
- Champs elysees
- paris
You can also specify a structured address by specifying the separate parts of the address : houseNumber, streetName, streetType, city, state, zipCode, etc.
A full list can be found here
- The country (not required for Gisgraphy v 4.0 and above) : The country where the place/address is. It is used to determine the postal address format and to improve performance. It will probably be optional in next version to ease the usability. The value must be the ISO 3166 Alpha 2 code of the country
Examples :
- postal : whether the given address is a postal address. default to false. In other words, if the address follow the specification or if it is a well-formed address as it was written on an envelope.
This parameter will enable the parsing of the address by the address parser before geocoding, this way, the relevance will be better because because if parsing is successful, we will know the meaning of each word. Note that you can also specify each field if you already know them.
Examples :
- The callback method name (optional), use to wrap the content into a (alphanumeric) Javascript method. Works only for script output formats (JSON, PHP, Ruby, Python)
Examples :
- executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)
- The indentation (optional) : indents the results. Default to false. Possible values are true|false (or "on" when used with the rest service. If you use a checkbox in a web form, to indent the results, the value will be "on" or "off", so for a simple use : the value of indent can be "true" or "on".
Actually, only XML can be indented. It is not a bug : Indent JSON is possible but decreases performance.
- the API key (optional) : the API key to use if you use premium webservices this parameter is useless for local installation
Web service
The geocoding web service uses a servlet to wrap the Java API. It links web parameters to a geocoding query and output the results to an HTTP feed.
It is recommended to explore the API
All the parameters should be case insensitive. If you've got some problems with case, please report a bug.
All the parameters should be encoded in
UTF-8 and the URL MUST be
encoded.
Here is a summary of the Web parameters mapping :
Parameter description | Web parameter name |
address | address |
A structured address | Any field that can describe an address. a list of fields can be found at here |
country | country |
postal | postal |
Callback method name | callback |
Output format | format |
Indent | indent |
apikey | api key (only for premium webservices, useless for local installation) |
Examples :
geocoding/geocode?address=108%20avenue%20des%20champs%20elysees%20paris&countrycode=FR
geocoding/geocode?address=108%20avenue%20des%20champs%20elysees%20paris&countrycode=FR&format=json
/geocoding/geocode?housenumber=105&streetname=avenue des champs elysees&city=paris
By default the geocoding service is mapped to /geocoding
pattern but you can change it in the WEB-INF/web.xml
Output fields description
The Geocoding service returns a list of addresses. It also return the parsed address in a parsedAddress field ()when the address parser is enabled.
Here is a description of all the output fields of an address that can be returned :
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 information that give extra information 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 is 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 is a 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 Philadelphia & W boulevard of liberty Washington |
streetTypeIntersection | The type of the intersection street | street,st,bd,dr,bvd,... | N street of Philadelphia & W boulevard of liberty Washington |
preDirectionIntersection | The cardinal direction before the name of the intersection street | N,NE;North | N street of Philadelphia & W boulevard of liberty Washington |
postDirectionIntersection | The cardinal direction after the name of the intersection street | N,NE;North | N street of Philadelphia & boulevard of liberty SOUTH Washington |
civicNumberSuffix | The number that follows 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)");
//if the parser is enabled or if the geocoder is called with a structured address
//then, the the parsedAddress field is filled.
System.out.println("parsed address : "+result.getParsedAddress());
for (Address address : results.getResult()){
System.out.println("housenumber : "+address.getHouseNumber());
System.out.println("streetType : "+address.getStreetType());
System.out.println("streetname : "+address.getStreetName());
System.out.println("PObox : "+address.getPOBox());
System.out.println("lat : "+address.getlat());
System.out.println("long : "+address.getLng());
System.out.println("city : "+address.getCity());
System.out.println("district : "+address.getDistrict());
System.out.println("state : "+address.getState());
//see all fields description above...
}
You can output results to an OutputStream (useful for servlet use) or a String.
The API is thread safe.
It is possible to create a query directly from an HTTP servlet request
Adress Parser
The International address parser is based on a modular engine, The address-parser is now a spin off and has a dedicated site:
http://address-parser.net
You can try it for free
Reverse geocoding service
Description
The Reverse geocoding service allows to search for an address for a given GPS position.
Output formats and languages
The following languages are supported :
- XML
- JSON
- PHP
- Ruby
- Python
- GeoRSS
Parameters
- The latitude (north-south) for the location point to search around. The value is a floating number, between -90 and +90. It uses GPS coordinates. This parameter is required.
Examples :
- The longitude (east-West) for the location point to search around. The value is a floating number between -180 and +180. It uses GPS coordinates. This parameter is required.
Examples :
- The callback method name (optional), used to wrap the content into a method name, must be alphanumeric and operates only for script output (JSON,PHP,Ruby,Python)
Examples :
- executeCallback :(will output "executeCallback(RESULT_FEED);" then if you evaluate this string the method will be called implicitly)
- The output format (optional) : The formats available are :
- XML (Default)
- JSON
- Python
- Ruby
- PHP
- YAML
- The indentation (optional) : indents the results. Default to false. Possible values are true|false. If you use a checkbox in a web form to indent the results, the value will be "on" or "off", so for a simple use : the value of indent, for the web service can be "true" or "on".
Actually, only XML can be indented. It is not a bug : Indented JSON is possible but decreases performance.
- the API key (optional) : the API key to use if you use premium webservices this parameter is useless for local installation
Web service
The reverse geocoding web service uses a servlet to wrap the Java API. It links web parameters to a reverse geocoding query and output the results via HTTP.
It is recommended to explore the API
All the parameters should be case insensitive. if you've got some problems with case, please notify a bug.
All the parameters should be encoded in
UTF-8 and the URL MUST be
encoded.
Here is a summary of the Web parameters mapping :
Parameter description | Web parameter name |
Latitude | lat |
Longitude | lng |
Callback method name | callback |
Output format | format |
Indent | indent |
apikey | api key(only for premium webservices, useless for local installation) |
Examples :
http://localhost:8080/reversegeocoding/search?lat=4.5&lng=5.7&format=json&callback=doit&indent=true
http://localhost:8080/reversegeocoding/search?lat=4.5&lng=5.7
Output fields description
Here is a description of all the output fields, :
Field | Description | Applicable for |
error | A String only present if an error occurred (e.g : empty Latitude or longitude) | When error occurred |
numFound | The number of results to display with this query (actually always 1) | |
QTime | The execution time of the query in ms | |
distance | The distance between the point and the address found | |
houseNumber | The house number of the address | |
name | The name of the address (could be a shop name, etc.) | |
streetName | The name of street of the address (could be a shop name, etc.), it could be null (even if the house number is not), if the name of the street is unknown | |
city | The city of the address | |
citySubdivision | a more precise information than the city (quarter, place,...) | |
state | The state of the address | |
countryCode | The countrycode of the address | |
geocodingLevel | information on how deep the reverse geocoding was able to do (house number, street, city) | |
lat | The latitude of the middle of the street(north-south) | |
lng | The longitude of the middle of the street(east-west) | |
Java API
The geoloc API looks like this
Point point = GeolocHelper.createPoint(LONGITUDE, LATITUDE);
Output output = Output.withFormat(OUTPUTFORMAT)
.WithIndentation();
ReverseGeocodingQuery query = new ReverseGeocodingQuery(point, Output.withFormat(OutputFormat.JSON).withIndentation());
ReverseGeocodingService service = new ReverseGeocodingService();
AddressResultsDto result = service.executeQuery(query);
System.out.println("reverse geocoding took "+result.getQTime()+" ms");
System.out.println("reverse geocoding find address "+result.getResult()+" ms");
Click on the UPPERCASE parameters above to see the description of the parameter.
The methods are designed with
DSL (Domain Specific Language), and can be chained as shown in the example above.
You can output results to an OutputStream (useful for servlet use) or a String.
The API is thread safe.
It is possible to create a query directly from an HTTP servlet request
Street / tracking service
Description
The street service allows you to search for street by GPS position.
you can :
- Specify GPS position
- Give the beginning or a part of the name of the street (useful for autocompletion)
- Limit search to a specific type (e.g : Pedestrian, highway, residential, ... 25 types available)
- 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, applies only to XML, not to JSON for performance reasons. May change in next version)
The street search service searches for the nearest street based on the shape of the streets, not the middle point. It is recommended to use this service with OpenGTS or if you want to search the nearest distance to a street. It is recommended to use the fulltext search engine with placetype=street to search by name, the fulltext engine search around a point, it is more like a restriction and distance is the one to the middle of the street. Street search service is the one to use when GPS is more important than name.
Actually the street search doesn't return house numbers (probably in next version). If you want house numbers you have to use the fulltext service
Gisgraphy is designed to allow search with auto completion / suggestions :
- To search for streets by entire name use the fulltext search (you can also specify GPS coordinate, and change the 'allwords required' option to ease the search).
- To do auto completion / suggestion use the fulltext webservice
If you don't specify the lat/lng and do a search that 'contains', indexes won't be used, so performance will be poor. With fulltext search performance will be OK.
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 floating number, between -90 and +90. It uses GPS coordinates. It could be optional but needs to be valid if specified.
Examples :
- The longitude (east-West) for the location point to search around. The value is a floating number between -180 and +180. It uses GPS coordinates. It could be optional but needs to be valid if specified.
Examples :
- A part of the name of the street (optional) or the name of the street : limits the search to the street that starts/contains 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 an email
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 the 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 + 10. Max = 50 (can be changed)
- 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 : Whether (or not) we want the distance field to be output. Default to true. This option is useful to improve the performance 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".
- the street type (optional) : allow to filter the search for a particular street type. The street type is one of the street type available
Actually, only XML can be indented. It is not a bug : Indented JSON is possible but decreases performance. If it is a critical need you can see an example of how indented JSON in the source code of streetSearchEngine.
- the API key (optional) : the API key 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.
It is recommended to explore the API
All the parameters should be case insensitive. if you've got some problems with case, please notify a bug.
All the parameters should be encoded in
UTF-8 and the URL MUST be
encoded.
Here is a summary of the Web parameters mapping :
Parameter 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 | api key(only for premium webservices, useless for local installation) |
Examples :
http://localhost:8080/street/streetsearch?lat=4.5&lng=5.7&radius=5000&from=1&to=10&format=xml&name=strip&indent=true
http://localhost:8080/street/streetsearch?lat=4.5&lng=5.7
Actually, the webservice limits the number of results to 50, but it can be changed (at compilation time)
street type
Streets are group by type. Here are the possible values :
- RESIDENTIAL
- SERVICE
- UNCLASSIFIED
- TRACK
- FOOTWAY
- TERTIARY
- PATH
- SECONDARY
- PRIMARY
- BUS_STOP
- TURNING_CIRCLE
- CROSSING
- CYCLEWAY
- TRUNK, TRAFFIC_SIGNALS
- MOTORWAY
- MOTORWAY_LINK
- ROAD
- LIVING_STREET
- STEPS
- PEDESTRIAN
- TRUNK_LINK
- STREET_LAMP, PRIMARY_LINK
- MOTORWAY_JUNCTION
- SECONDARY_LINK
- STOP
- CONSTRUCTION
- TERTIARY_LINK
- BRIDLEWAY
- MINI_ROUNDABOUT
- PLATFORM
- PROPOSED
- GIVE_WAY
- SPEED_CAMERA
- EMERGENCY_ACCESS_POINT
- MILESTONE
- RACEWAY
- FORD
- REST_AREA
- PASSING_PLACE
- SERVICES
- ABANDONED
- ELEVATOR
- UNSURFACED
- EMERGENCY_BAY
- STILE
- INCLINE_STEEP
- INCLINE
- STREET_LIGHT
note that in v 3.0 the street type were different (they have been updated to reflect the OpenStreetMap evolution):
- BYWAY
- MINOR
- SECONDARY_LINK
- CONSTRUCTION
- UNSURFACED
- BRIDLEWAY
- PRIMARY_LINK
- LIVING_STREET
- TRUNK_LINK
- STEPS
- PATH
- ROAD
- PEDESTRIAN
- TRUNK
- MOTROWAY
- CYCLEWAY
- MOTORWAY_LINK
- PRIMARY
- FOOTWAY
- TERTIARY
- SECONDARY
- TRACK
- UNCLASSIFIED
- SERVICE
- RESIDENTIAL
Output fields description
Here is a description of all the output fields, :
Field | Description | Applicable for |
error | A String only present if an error occurred (e.g : empty Latitude or longitude) | When error occurred |
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 between the point and the nearest point to the street in meters | |
name | The name of the street | |
gid | Unique id of the street, it is unique between GeoNames and OpenStreetMap | |
openstreetmapId | OpenStreetMap unique id of the street | |
isIn | Information on the city where the street is (depends on OpenStreetMap 'is_in' field), the city in general | |
isIn | Information on the city where the street is (depends on OpenStreetMap 'is_in' field), the city in general | |
isInPlace | Information on the place where the street is. Often something more precise than the city or municipality | |
isInAdm | Information on the administrative division where the street is: region, district,... | |
isInZip | Information on the zip where the street is. only one is output. | |
length | the length of the street in meters | |
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 an HTTP servlet request
Fulltext / autocompletion service
Description
The fulltext service allows you to search for features / places / POIs / cities / zipcodes/ administartion divisions/ street. It allow to do autocompletion / autosuggetion
you can
- Specify one or more words
- search on part of the name (auto completion / suggestion)
- Search for text or zip code
- Specify a GPS restriction (promote nearest, not sorted but has an impact on the score)
- Limit the results to a specific
- Paginate the results
- Specify the output 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 can be a zip code, a string or one or more strings.
Examples :
You can search for a place or feature by id by specifying feature_id:XXXXXX Where XXXXXX is the id of the feature
You can search for a place or feature by OpenStreetMap id by specifying openstreetmap_id:XXXXXX Where XXXXXX is the id of the feature in OpenStreetMap
- All words required (optional): Whether the fulltext engine should considers all the words specified as required. Defaults to false (since v 4.0). possible values are true|false (or "on" when used with the rest service)
- The latitude (optional) (north-south) for the location point to search around and restrict the search results. The value is a floating number and can be negative. It uses GPS coordinates. If lat/long is provided then the nearest place will be promoted (not sorted but has an impact on the score).
Examples :
- The longitude (optional) (east-west) for the location point to search around and restrict the search results. The value is a floating number and can be negative. It uses GPS coordinates. If lat/long is provided then the nearest place will be promoted (not sorted but has an impact on the score)
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).
If the radius is > 0, then the result will be filtered by a bounding box If the radius is equal to 0 then it will only promote the nearest.
Examples :
- suggest (optional) : If this parameter is set then it will search in part of the names of the street, place,.... It allow you to do auto completion auto suggestion. See the Gisgraphy leaflet plugin for more details.
The JSON format will be forced if this parameter is true. See auto completion / suggestions engine for more details
.
- 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. max = 20 (can be changed)
- 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 such as the AlternateName AdmNames and countryname belong to a certain language code. The language parameter can limit 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 description of output fields : see
below.
- The placetype(s) (optional) : limit the search to the one or more place type (you can specify more than one). Place type regroups some feature class and feature code. You need to specify the class corresponding 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 specified 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).
Autocompletion / suggestions
Gisgraphy can provide, via the fulltext search engine, a very powerful auto completion / suggestion engine.
combined with the other parameters of the fulltext engine (latitude, longitude, radius, countrycode,...),
It allow you to have a very powerful and personalized suggestion engine.
You can :
- Promote nearest by specifying radius to 0
- or...Suggest only in a bounding box by specifying a radius superior to 0
- Suggest place for a specific country with the countrycode parameter
- Detect or specify lat/long to improve user experience
- Detect GPS coordinate and resolve them as an address
- Detect degree / minute / second coordinates and resolve them as an address
- Use magic sentence
- Prefetch some results
- So much more...feel free to contact me me for more details
You can use the Gisgraphy js API to initiate an auto completion input text very simply, or use the Gisgraphy leaflet geocoder plugin to use autocompletion on a map.
There is also a reverse geocoding plugin.
Note that adding a Lat/Long and a radius impacts performance because the distance is calculated for all the results, but the relevance will probably be better : the user in 75% of use cases searches for something near them.
To do autocompletion, simply add the 'suggest' parameter to true. e.g
/fulltext/suggest?format=json&suggest=true&allwordsrequired=false&style=long&lat=50.4589901&lng=3.2124411&radius=0&placetype=city&placetype=adm&placetype=street&from=1&to=20&q=paris&apikey=12
See the Gisgraphy leaflet plugin for more details.
Web service
The full text web service use a servlet to wrap the Java API. It links web parameters to a fulltext query and output the results via HTTP.
It is recommended to explore the API
All the parameters should be case insensitive. If you've got some problems with case, please report a bug.
All the parameters should be encoded in
UTF-8 and the URL MUST be
encoded.
the API key (optional) : the API key to use if you use premium webservices this parameter is useless for local installation
Here is a summary of the Web parameters mapping :
Parameter name | Web parameter name | comment |
The searched text | q | |
all words required | allwordsrequired | |
Latitude | lat | |
Longitude | lng | |
Radius | radius | |
suggest | suggest | |
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 | |
api key | api key (only for premium webservices, useless for local installation) |
If you use a checkbox in a form to indent the results, the value will be "on" or "off", so for a simple use : the value of indent, for the fulltext web service can be "true" or "on".
Examples :
http://localhost:8080/fulltext/fulltextsearch?q=paris&from=1&to=10&format=xml&lang=fr&style=short&placetype=city&country=fr&indent=true
http://localhost:8080/fulltext/fulltextsearch?q=paris
Actually, the webservice limits the number of results to 10.
By default the fulltext service is mapped to /fulltext
pattern but you can change it in the WEB-INF/web.xml
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 occurred (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 |
score | a number that indicates the relevance of the result | 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 |
amenity | Informations on category of OpenStreetMap POIs | MEDIUM |
openstreetmap_map_url | The URL to get the location on OpenStreetMap.org | 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 on the city where the street / POI is (depends on OpenStreetMap 'is_in' field), the city in general (only for placetype street) | MEDIUM |
is_in_place | Information on the place where the street / POI is (quater, common place). Generally a place at a lower level than city | MEDIUM |
is_in_adm | Information of the administration division where the street / POI is. | MEDIUM |
is_in_zip | Information of the zipcode where the street / POI is (often fill for placetype street) | MEDIUM |
house_numbers | a list of all the house numbers and their coordinates (only for placetype street). house number are sorted | MEDIUM |
municipality | if the place is a municipality. it is usefull for geonames feature that don't have concept of 'city' but a populated place (that can be a quarter) | MEDIUM |
amenity | Informations on category of OpenStreetMap POIs | 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 live 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 currency 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 | List 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 |
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 ,
If you specify link as a languagecode, you will get the Wikipedia link | FULL |
fullyQualifiedAddress | NOT USED YET | N/A |
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")
.around(GeolocHelper.createPoint(54.2F, -95F))
.withRadius(1000).limitToCountryCode("FR");
String result = fullTextSearchEngine.executeQueryToString(fulltextQuery);
You can output results to an OutputStream (useful for servlet use) or a String.
The API is thread safe.
It is possible to create a query directly from an HTTP servlet request
The methods are designed with
DSL (Domain Specific Language), and can be chained as shown in the example above.
Geolocalisation service
Description
The geolocalisation service allows to search for features around a 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, applies 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 floating number and can be negative. It uses GPS coordinates.
Examples :
- The longitude (required) (east-West) for the location point to search around. The value is a floating number and can be negative. It uses 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 specified 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. Max = 10 (can be changed)
- 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 regroups some feature classes and feature codes. You need to specify the class corresponding to the place type you want to search. default : search for all features
For performance reasons, it is highly recommended you 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 : Whether (or not) we want the distance field to be filled. this option is useful when we don't care about the distance to improve the performance. 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 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 : Indentrf JSON is possible but decreases performance.
- the API key (optional) : the API key to use if you use premium webservices this parameter is useless for local installation
Web service
The geolocalisation web service uses a servlet to wrap the Java API. It links web parameters to a geoloc query and output the results via HTTP.
It is recommended to explore the API
All the parameters should be case insensitive. if you've got some problems with case, please report a bug.
All the parameters should be encoded in
UTF-8 and the URL MUST be
encoded.
Here is a summary of the Web parameters mapping :
Parameter 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 | api key (only for premium webservices, useless for local installation) |
Examples :
http://localhost:8080/geoloc/findnearbylocation?lat=4.5&lng=5.7&radius=5000&from=1&to=10&format=xml&placetype=city&indent=true
http://localhost:8080/geoloc/findnearbylocation?lat=4.5&lng=5.7
Actually, the webservice limits the number of results to 10.
By default the geolocalisation service is mapped to /geoloc
pattern but you can change it in the WEB-INF/web.xml
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 occurred (e.g : empty Latitude or longitude) | When error occurred |
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 between 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 |
openstreetmapId | OpenStreetMap unique id of the feature | All placetypes |
is_in | Information of the city where the street / POI is (depends on openstreetmap 'is_in' field), the city in general (only for placetype street) | MEDIUM |
is_in_place | Information of the place where the street / POI is (quarter, common place). Generally a place at a lower level than city | All placetype |
is_in_adm | Information of the administration division where the street / POI is. | All placetype |
is_in_zip | Information of the zipcode where the street / POI is | (often fill for placetype street) |
oneWay | Whether the street is a one way street or not | Street only |
streetType | the type of the street | Street only |
length | length of the street in meters | Street only |
countryCode | The ISO 3166 country code | All placetypes |
openstreetmap_map_url | The URL to get the location on OpenStreetMap.org(since v3.0 beta3) | All placetypes |
google_map_url | The URL to get the location on Google Map | All placetype |
yahoo_map_url | The URL to get the location on Yahoo Map | All placetypes |
country_flag_url | The relative URL to get the country flag image | All placetypes |
featureClass | The feature Class. More... | All placetypes |
featureCode | The feature Code. More... | All placetypes |
placeType | The Type of Feature see faq | All placetype |
population | How many people live in this feature | All placetype |
lat | The latitude (north-south) | All placetypes |
lng | The longitude (east-West) | All placetypes |
adm1Code | The internal code for the administrative division of level 1 | All placetypes |
adm2Ccode | The internal code for the administrative division of level 2 | All placetypes |
adm3Code | The internal code for the administrative division of level 3 | All placetypes |
adm4Code | The internal code for the administrative division of level 4 | All placetypes |
adm1Name | The name of the administrative division of level 1 | All placetypes |
adm2Name | The name of the administrative division of level 2 | All placetypes |
adm3Name | The name of the administrative division of level 3 | All placetypes |
adm4Name | The name of the administrative division of level 4 | All placetypes |
timezone | The time zone (e.g : Europe/Paris) | All placetypes |
gtopo30 | Average elevation of 30'x30' (ca 900mx900m) area in meters | All placetypes |
elevation | The elevation in meters | All placetypes |
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 feature | 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 |
iso3166NumericCode | The iso 3166 numeric code of the country | Country |
phonePrefix | The phone prefix of the country | Country |
postalCodeMask | The mask that all postal codes 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 an HTTP servlet request
Client libraries
Client libraries exists in several languages. Consult the client library 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 are 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 that you change the default users of the admin interface. To do so : login as 'admin' with password 'admin' or edit the 'insert_users.sql' file in the sql directory, set the users / passwords / roles, and run the script
Import data
To import data, you must log as a user with admin rights. Then go to the Administration menu -> Run importer. A wizard will guide you to choose the correct options.
The importer process may takes more than 40 hours, depending on how much data you import and the machine the importer runs on. (some
dumps are available on the download server)
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 that you change the default users of the admin interface. To do so, login as 'admin' with password 'admin'
Protect WebServices
Some users wants to restrict the SolR engine to the host 'localhost' in order to disallow users to ask the SolR search engine directly. You can use a firewall and restrict the access of the Webapp with the following code
With Tomcat :
<Context path="/path/to/secret_files">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127.0.0.1" deny=""/>
</Context>
With Jetty :
A server configuration-XML-file can look something like this:
<Configure class="org.mortbay.jetty.Server">
...
<Call name="addContext">
...
<Call name="addHandler">
<Arg>
<New class="IPAccessHandler">
<Set name="Standard">deny</Set>
<Set name="AllowIP">192.168.0.103</Set>
<Set name="AllowIP">192.168.0.100</Set>
</New>
</Arg>
</Call>
See more on http://www.jdocs.com/jetty/5.1.11.rc0/org/mortbay/http/handler/IPAccessHandler.html
Performance
Jmeter
Some Jmeter benchmarks are available (scripts and results) here.
Database Optimisation
In order to have good performance it is recommended that you use database indexes. As far as I know it is possible to tell Hibernate to create indexes but it is not possible to choose the type of index (BTREE,GIST, and so on) with annotations. You must create your own index with the following code :
DROP INDEX IF EXISTS locationindex ;
CREATE INDEX locationindex
ON gisfeature
USING gist
("location");
VACUUM FULL ANALYZE;
You can do this for all the tables that have Geometry columns.
A script named 'createGISTIndex.sql' is provided in the 'SQL' directory in the Gisgraphy distribution to create all the GIST indexes for all the tables.
You will have GREATER performance if you specify a placetype; if you search for placetype 'gisFeature', your query will be slower.
You can 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 performance if you run Gisgraphy and the SolR server in two distinct JVMs.
To run SolR in a separate JVM, copy the SolR Directory (default parameter) with the schema.xml, SolRconfig.xml, the data directory, and so on to a SolR distribution and start it with java -jar start.jar
(or an other way of your choice, that's the easy way).
Then you can remove the SolR.war from the Gisgraphy release and configure the fulltextsearch URL to point to the new SolR URL.
It is also recommended to use the Sun JVM (not the GCJ one) and to use the VMargs -server
To have great performance we recommend that you use the Sun -jdk version 6.0.
Other tips
We strongly recommend that you install Gisgraphy (using SolR) on a Linux or Unix OS. Due to a JVM bug and other reasons, Windows users will get less performance than Unix users.
If you want to tune performance you should call the /SolR/admin/stats.jsp page and watch the cache section. hitRatio, eviction and warmupTime values can be useful. Read the SolR Caching Wiki page for more information.
The /SolR/admin/luke page can also give you interesting information (if index is optimized,...)