Gisgraphy user guide




Introduction

About

Since 2006, Gisgraphy has been a free, open-source framework that offers the ability to do geolocalisation and geocoding via Java APIs or REST web services. Because geocoding is nothing without data, it provides an easy-to-use importer that will automagically download and import the necessary (free) data to your local database (OpenStreetMap, Openaddresses, GeoNames, and Quattroshapes : more than 500 million entries). You can also add your own data with the Web interface or the import connectors provided. gisgraphy is production ready and has been designed to be scalable (load balanced), high-performance and used in other languages than just Java : results can be output in XML (default), Json, php, Python, YAML, ruby, Atom, and Georss. Some popular GPS tracking System (OpenGTS or Traccar ) also includes a Gisgraphy client...Gisgraphy is a framework. As a result, it's flexible and powerful enough to be used in a lot of different use cases. read more Here are the main functionalities :
  • Importers for OpenStreetMap, Openaddresses, Geonames and Quattroshapes data.
  • Worldwide geocoding / worldwide reverse geocoding / street search Web services;
  • Useful fields for routing and vehicle tracking : lanes, toll, azimuth, surface, max speed, length, oneway
  • REST web service
  • Postcode / zip code search
  • Powerful Autocompletion / suggestion engine
  • Leaflet plugins and JS API (aka : Gisgraphy-js-API)
  • Installation with Docker images or installation script
  • Point of interests (POIs) search
  • Fuzzy search and geocoding
  • Postal address formatting depending on country specifications
  • House number interpolation
  • You can choose the country you need or all the planet
  • Several output formats supported : XML (default), JSON, PHP, Python, YAML, ruby, Atom and Georss
  • Full-text search (based on Lucene / Solr with default filters optimized for city search (case insensitivity, separator characters stripping, ..) via a Java API or a web service
  • Find nearby function (with limits, pagination, restrict to a specific country and/or language and other useful options) via a Java API or a web service
  • An admin / back office with statistics
  • Fully replicated / scalable / high performance / cached services
  • Search for zip code name, IATA, ICAO
  • Traccar, OpenGTS client
  • Geocoding with location bias or in a bounding box
  • Internationalized (with support of Cyrillic, Arabic, Chinese,... alphabet)
  • Dojo widgets / prototype / Ajax to ease search but can be used it even if Javascript is not enabled on the client side
  • Opensearch module
  • Platform / language independent
  • Provides all the countries flags in SVG and PNG format
  • ...

Quick start

Please consult the quick start guide.

Which technologies are used ?

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

License

The Gisgraphy project (www.gisgraphy.com) is a free open source project under the LGPL license V3. For data license, please consult the attributions page.

Premium

We also provide premium hosted web services with SLA. If you want to use Gisgraphy off-line, you can install it locally and run an import. You can also order some dump of preprocessed data (inject a premium dump took few hours but import data by your own will take days). If you are interested in data (don't want to use gisgraphy), we also provide some data (addresses, streets, cities, more) in CSV format

Installation

Please go the the installation page

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. You can specify a structured address or not, search around a point or in a bounding box. Fuzzy search, house number interpolation, country detection is also possible. The geocoder can provide additional information on the address as the 'formatedfull' field (the fully qualifed name) and the 'postalformat' (address as if it was written on an envelope. It use an internal address parser)


Important note : the geocoding service take an address as input (cities, administrative divisions, addesses), but not POIs : don't provide POIs (e.g : arc de triomphe) or you will not get (logically) a relevant result. To search for POIs, use the fulltext webservice. The reasons are : first, geocoding service do some optimisations on addresses search (house number extraction, interpolation, street synonyms,... that are not suitable for POIS search, secondly, POIs not always have address (street or house number) e.g : arc de triomphe or central park does not have address, just a GPS popsition. We plan to allow search of POIs with the geocoding service, There is currently a private experimentation.

Endpoint

The endpoint is

/geocoding/geocode

Example :

https://services.gisgraphy.com/geocoding/geocode?address=1 avenue des champs elysees 75003 paris&country=FR

Parameters

All the parameters are case insensitive and should be encoded in UTF-8 and the URL MUST be encoded.

Here is a summary of the Web parameters :

ParameterDefaultDescription
address-Required. A postal address, structured or not, a street, a city, a postal code, a country, or a combination. You can also specify a structured address by specifying the separate parts of the address : houseNumber, streetName, street type, city, state, zipCode, etc. A full list can be found here
A structured address-(required if the 'address' parameter is not specified). Any field that can describe an address. A list of fields can be found at here
lat-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. Can be comma or point separated. Search around a GPS point and get nearest results first, or search in a bounding box by specifying a radius. Examples : 42.5 or 42,5
long-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. Can be comma or point separated. (see also 'lat' parameter). Examples : 3.5 or 3,5
radius10000Radius in meters. Search around a GPS point and get nearest results first, or search in a bounding box
  • if not specified, the default radius is 10000.
  • if radius == 0 : it promote nearest results without boundingbox
  • if radius is specified : it promote nearest results and filter result in boundingbox
fuzzyfalseAllow search in fuzzy mode. This allows doing spell checking (for instance it can find a misspelled address). A fuzzy search needs a lot of processor and memory and increase the response time. if fuzzy is set to true : it searches the address and if nothing is found, then it tries in fuzzy mode. Fuzzy is not active by default, you have to manually enable it because fuzzy search require times to process and can cause some unwanted delay in system that requires a quick answer. Note that when fuzzy search has been done a field message is set to fuzzy:active
country-Restrict search for the specified country. The value must be the ISO 3166 Alpha 2 code of the country
postal-This has been removed since Gisgraphy v 5.0 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 enabled 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.
limitnbresult10Limits the number of results to the specified value. If <=0. it is ignored.
callback-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)
formatXMLOutput formats and languages The following languages are supported :
  • XML
  • JSON
  • PHP
  • Ruby
  • Python
  • YAML
indent-Indents the results. 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".
apikey-The api key (only for premium webservices, useless for local installation)

Examples :

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

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

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


Output fields description

The Geocoding service returns a list of addresses. Here is a description of all the output fields of an address :
fielddescriptionExamples of valueExamples in address
houseNumberOfficial number assigned to an address by the municipality, several languages supported3;151-125;eight123 street of Philadelphia city, apt 5A, Washington
idUnique identifier (but not stable, change at each import of data) of the address561364654N/A
score number that give an indication on the relevance, it can give information if the address found is far form the searched one and then avoid some resultsSaint Bartus
latThe latitude of the address (the latitude of the administrative centre for city and adm)43.5
lng The longitude of the address (the longitude of the administrative centre for city and adm)2.8
sourceIdReference in the original dataset (e.g : the geonames id or openstreetmap one)Saint Bartus
nameName of the place (and not the name of people that live at the address) restaurant Mac Fidle
zipCodeThe zip or post code98104100 MAIN ST POB 1022 SEATTLE WA 98104
adm1NameName of the first administrative division (the biggest)California
adm2NameName of the second administrative divisionClark County
adm3NameName of the third administrative division
adm4NameName of the fourth administrative division
adm5NameName of the fifth administrative division
streetRefRoad (national/international) reference of the street A25 / E 42
QuarterQuater where the address is Saint Bartus
stateBiggest administrative divisionSaint Bartus
formatedFullFully qualified address with all the admXnames and zip
formatedPostalAddress as it should be written on an envelop (no waranty)
houseNumberInfoAll information that give extra information on the house numberbis, ter, quater,125 bis rue de la france 75000 Paris
streetNameThe official name of the street or the ordinal numberMain, 8TH100 MAIN ST POB 1022 SEATTLE WA 98104
streetTypeThe type of the streetstreet,st,bd,dr,bvd,...100 MAIN ST POB 1022 SEATTLE WA 98104
cityThe city or locality, a small town or village name sometimes is included in an address when the Delivery Point is outside the boundary of the main Post Town that serves it.APPLEFORDLeda Engineering Ltd APPLEFORD ABINGDON OX14 4PG
dependentLocality"Sub" city attached to a big cityDublinboulevard of liberty Washington
PostTowna city is a required part of all postal addresses in the United KingdomLondon49 Featherstone Street LONDONEC1Y 8SY
stateThe state or county when applicable, can be fullname or abbreviationWA100 MAIN ST POB 1022 SEATTLE WA 98104
districtThe district, mainly use for RussiaALEKSCEVSKTY (r-n)ul. Lesnaya d. 5 pos. Lesnoe ALEKSCEVSKTY r-n VORONEJSKAYA obl 247112 RUSSIAN FEDERATION
quarterA section of an urban settlementDOĞANBEY MAH(turkey),French QuarterMebusevleri Mah. Önder Cad. Ankara Ap. 11/8 ALEKSCEVSKTY
civicNumberSuffixThe number that follows the house number (Canada only)1/210-123 1/2 main street NW MONTREAL QC H3Z 2Y7
countryThe country nameUSA
United States
France
Paris - France
countrycodeThe countrycode given in the requestFR
US
DE
N/A


Example of feed

Example of feed : https://services.gisgraphy.com/geocoding/geocode?address=103%20avenue%20des%20champs%20elysees%20paris&countrycode=FR :

<results>
	<numFound>3</numFound>
	<QTime>28</QTime>
	<attributions>http://www.gisgraphy.com/attributions.html</attributions>
	<result>
		<id>135539289</id>
		<lng>2.3000703000000002</lng>
		<lat>48.871824800000006</lat>
		<houseNumber>103</houseNumber>
		<streetName>Avenue des Champs-Élysées</streetName>
		<streetType>PRIMARY</streetType>
		<zipCode>75008</zipCode>
		<city>Paris</city>
		<state>Île-de-France</state>
		<countryCode>FR</countryCode>
		<geocodingLevel>HOUSE_NUMBER</geocodingLevel>
		<adm1Name>France métropolitaine</adm1Name>
		<adm2Name>Île-de-France</adm2Name>
		<adm3Name>Paris</adm3Name>
		<formatedFull>103 Avenue des Champs-Élysées, Paris, Île-de-France,
			France métropolitaine, (75008), France</formatedFull>
		<formatedPostal>103 Avenue des Champs-Élysées, 75008, Paris
		</formatedPostal>
		<score>23.053549</score>
		<sourceId>314456034</sourceId>
	</result>
	......
</results>

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


The API is thread safe.

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.

Endpoint

The endpoint is

/reversegeocoding/search?

Example :

https://services.gisgraphy.com/reversegeocoding/search?format=json&lat=48.8723789988&lng=2.2996401787

Parameters

All the parameters are case insensitive and should be encoded in UTF-8 and the URL MUST be encoded.



Here is a summary of the Web parameters mapping :
ParameterDefaultDescription
Latitude-Required. 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. Can be comma or point separated. Examples : 3.5 or 3,5
Longitude-Required. 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. Can be comma or point separated. (see also 'lat' parameter). Examples : 3.5 or 3,5
callback-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)
formatXMLOutput formats and languages The following languages are supported :
  • XML
  • JSON
  • PHP
  • Ruby
  • Python
  • YAML
indentfalseIndents the results. 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".
apikey-The 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, :
FieldDescriptionApplicable for
errorA String only present if an error occurred (e.g : empty Latitude or longitude)When error occurred
numFoundThe number of results to display with this query (actually always 1)
QTimeThe execution time of the query in ms
distanceThe distance between the point and the address found
geocodingLevelinformation on how deep the reverse geocoding was able to do (house number, street, city)
latThe latitude of the middle of the street(North-South)
lngThe longitude of the middle of the street(East-West)
houseNumberThe house number of the address
nameThe name of the address (could be a shop name, etc.)
streetNameThe name of street of the address (could be a shop name, etc.), it could be null (even if the house number is not), if the name of the street is unknown
cityThe city of the address
citySubdivisiona more precise information than the city (quarter, place,...)
stateThe state of the address
idunique identifier (but not stable, change at each import of data) of the address
namename of the place (and not the name of people that live at the address)
adm1Namename of the first administrative division (the biggest)
adm2Namename of the second administrative division
adm3Namename of the third administrative division
adm4Namename of the fourth administrative division
adm5Namename of the fifth administrative division (the smallest)
lat_admin_centrethe latitude of the administrative center (not the geometrique one)
lng_admin_centrethe longitude of the administrative center (not the geometrique one)
formatedFullfully qualified address with all the admXnames and zip
formatedPostalAddress as it should be written on an envelop (no waranty)
surfacetell the physical surface of the street (paved, asphalt,...)
speedModetells about the way the maxspeed and maxspeedbackward come from. Can be OSM when comes from openstreetmap or CALCULATED when it is based on general consideration as the speed limit in a city)
maxSpeedlegal speed limit for general traffic on the forward direction (not side), if only a number stands for km/h, otherwise the unit is to be specified (mph for instance)
maxSpeedBackwardlegal speed limit for general traffic on the backward direction (not side), if only a number stands for km/h, otherwise the unit is to be specified (mph for instance)
azimuthStartnumber in degres of the azimuth (ordinal direction) at the begining of the street (useful for GPS to indicates to take to the north for instance or to calculate the difference between two streets and tell the user to take to the right, left, or to see if a street is a line or not by comparing the difference between the azimuth at the start and at the end, etc)
azimuthEndnumber in degres of the azimuth (ordinal direction) at the end of the street (see bellow)
lengthlength of the segment (a street can be composed of several segment) of the street (in meter)
oneWaytells wether the street is a oneway street or not (no value does not mean anything, can be both)
sourceIdreference in the original dataset (e.g : the geonames id or openstreetmap one
lanesnumber of lanes of the streets for this particular segment
tollwhether some fee must be paid by general traffic to use the street (no value does not mean anything, can be both)
streetRefroad (national/international) reference of the street
countryCodeThe countrycode of the address


Here is an exemple of Postgres function (that can be adapt) to calculate cardinal direction from azimuth
CREATE OR REPLACE FUNCTION ST_CardinalDirection(azimuth float8) RETURNS character varying AS '
 CASE  WHEN $1 < 0.0 THEN '''' 
 WHEN degrees($1) < 22.5 THEN ''N''
 WHEN degrees($1) < 67.5 THEN ''NE''
  WHEN degrees($1) < 112.5 THEN ''E''
  WHEN degrees($1) < 157.5 THEN ''SE''
  WHEN degrees($1) < 202.5 THEN ''S''
  WHEN degrees($1) < 247.5 THEN ''SW''
  WHEN degrees($1) < 292.5 THEN ''W''
  WHEN degrees($1) < 337.5 THEN ''NW''
  WHEN degrees($1) <= 360.0 THEN ''N''
 END;'
LANGUAGE sql IMMUTABLE COST 100;

Example of feed

Example of feed : https://services.gisgraphy.com/reversegeocoding/?lat=48.85&lng=2.35 :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
	<numFound>1</numFound>
	<QTime>51</QTime>
	<attributions>http://www.gisgraphy.com/attributions.html</attributions>
	<result>
		<id>133785337</id>
		<lng>2.3497571</lng>
		<lat>48.850065400000005</lat>
		<name>Aux Verres de Contact</name>
		<houseNumber>52</houseNumber>
		<streetName>Rue de Bièvre</streetName>
		<zipCode>75005</zipCode>
		<city>Paris</city>
		<state>Île-de-France</state>
		<countryCode>FR</countryCode>
		<geocodingLevel>HOUSE_NUMBER</geocodingLevel>
		<distance>19.311531982696714</distance>
		<adm1Name>France métropolitaine</adm1Name>
		<adm2Name>Île-de-France</adm2Name>
		<adm3Name>Paris</adm3Name>
		<formatedFull>52 Rue de Bièvre, Paris, Île-de-France, France
			métropolitaine, (75005), France</formatedFull>
		<formatedPostal>Aux Verres de Contact, Aux Verres de Contact 52 Rue de
			Bièvre, 75005, Paris</formatedPostal>
		<surface>asphalt</surface>
		<speedMode>OSM</speedMode>
		<maxSpeed>15</maxSpeed>
		<azimuthStart>51</azimuthStart>
		<azimuthEnd>39</azimuthEnd>
		<length>185.743627659</length>
		<oneWay>true</oneWay>
		<sourceId>4221405</sourceId>
	</result>
</results>

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");


The API is thread safe.

Street / tracking service

Description


The street service allows you to search for streets by GPS position. There is some popular GPS tracking System (OpenGTS or Traccar ) also includes a Gisgraphy client. The main difference with the reverse geocoding service is that the street search returns a list of streets while the reverse geocoding return one address. You can also use this web service or the reverse geocoding one in GTS software if house numbers matter.
you can :
  • Specify GPS position
  • Give the beginning or a part of the name of the street
  • 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

The street search service searches for the nearest streets based on the shape of the streets, not the middle point.
Differences with other web services that also allow returning streets :
  • Use this service if you want to search streets around a GPS point (and optionally specified a part of the name of the street) and when house number doesn't matters and doesn't need to be returned
  • Use the full-text search engine with 'placetype=street' to search streets when you have the full name. The full-text engine can also search around a GPS point but the returned distance is the one to the middle of the street while the one for reverse geocoding and streetsearch is the one to the nearest point on the street.
  • Use the reverse geocoding when House numbers matters and need to be returned and if you don't have to restrict by street type or one way

Endpoint

The endpoint is

street/search?

Example :

https://services.gisgraphy.com/reversegeocoding/search?format=json&lat=48.8723789988&lng=2.2996401787&from=1&to=10

Parameters

All the parameters are case insensitive and should be encoded in UTF-8 and the URL MUST be encoded.



Here is a summary of the Web parameters mapping :
ParameterDefaultDescription
lat-Required. The latitude (North-South) for the location point to search around. The value is a floating number between -90 and +90 and can be negative. It uses GPS coordinates. Can be comma or point separated. Examples : 3.5 or -42,5
lng-Required. The longitude (East-West) for the location point to search around. The value is a floating number between -180 and +180 and can be negative. It uses GPS coordinates. Can be comma or point separated. (see also 'lat' parameter). Examples : 3.5 or -42,5
radius10000The 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).
name-A part of 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.
onewayfalsewhether the street should be a oneWay street. Limits the search to the street that are one way street
Type of the street-The street type. Allow to filter the search for a particular street type. The street type is one of the street type available
distancetrueDistance field : Whether (or not) we want the distance field to be output. 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".
from1Start 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.
tofrom+10End pagination Index (optional) : The last pagination index. if < 1 or not specified, it will be set to startindex + 10. Max = 50 (can be changed)
callback-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)
formatXMLOutput formats and languages The following languages are supported :
  • XML
  • JSON
  • PHP
  • Ruby
  • Python
  • YAML
indentfalseIndents the results. 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".
apikey-The api key (only for premium web services, 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



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

Output fields description

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


Example of feed

Example of feed : https://services.gisgraphy.com/street/?lat=40.76497&lng=-73.97828&name=avenue&to=2 :

<results xmlns="http://gisgraphy.com">
	<numFound>2</numFound>
	<QTime>294</QTime>
	<query>avenue</query>
	<result>
		<name>6½ Avenue</name>
		<distance>53.39489268</distance>
		<gid>182181724</gid>
		<openstreetmapId>458448238</openstreetmapId>
		<streetType>PEDESTRIAN</streetType>
		<oneWay>false</oneWay>
		<countryCode>US</countryCode>
		<length>15.965253731</length>
		<lat>40.764992750000005</lat>
		<lng>-73.9789701</lng>
		<isIn>New York City</isIn>
		<isInPlace>Manhattan Community Board 5</isInPlace>
		<isInAdm>New York</isInAdm>
		<adm1Name>New York</adm1Name>
		<adm2Name>New York City</adm2Name>
		<adm3Name>New York County</adm3Name>
		<fullyQualifiedName>6½ Avenue, Manhattan Community Board 5, New York
			City, New York County, New York City, New York (NY), (10001)
		</fullyQualifiedName>
		<azimuthStart>231</azimuthStart>
		<azimuthEnd>231</azimuthEnd>
		<label>6½ Avenue, New York City</label>
		<labelPostal>6½ Avenue, New York City, New York (NY) 10001
		</labelPostal>
		<zipCode>10001</zipCode>
		<source>OSM</source>
	</result>
	<result>
		<name>6½ Avenue</name>
		<distance>63.74618006</distance>
		<gid>182181645</gid>
		<openstreetmapId>458448233</openstreetmapId>
		<streetType>PEDESTRIAN</streetType>
		<oneWay>false</oneWay>
		<countryCode>US</countryCode>
		<length>42.194480857</length>
		<lat>40.7647734</lat>
		<lng>-73.97915375</lng>
		<isIn>New York City</isIn>
		<isInPlace>Manhattan Community Board 5</isInPlace>
		<isInAdm>New York</isInAdm>
		<adm1Name>New York</adm1Name>
		<adm2Name>New York City</adm2Name>
		<adm3Name>New York County</adm3Name>
		<fullyQualifiedName>6½ Avenue, Manhattan Community Board 5, New York
			City, New York County, New York City, New York (NY), (10001)
		</fullyQualifiedName>
		<azimuthStart>215</azimuthStart>
		<azimuthEnd>215</azimuthEnd>
		<label>6½ Avenue, New York City</label>
		<labelPostal>6½ Avenue, New York City, New York (NY) 10001
		</labelPostal>
		<zipCode>10001</zipCode>
		<source>OSM</source>
	</result>
	<attributions>http://www.gisgraphy.com/attributions.html</attributions>
</results>

Java API

The geoloc API looks like this
	Point point = GeolocHelper.createPoint(LONGITUDE, LATITUDE);
	Pagination pagination = paginate().from(STARTINDEX).to(ENDINDEX);
	Output output = Output.withFormat(OUTPUTFORMAT)
						  .WithIndentation();
	StreetSearchQuery query = new StreetSearchQuery(point,RADIUS,
			pagination,output,STREETTYPE,
			ONEWAY,NAME);
	String results = streetSearchEngine.executeQueryToString(query);
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 API is thread safe.



search / autocompletion service

Description


The place service allows you to search for features / places / POIs / cities / zipcodes/ administartion divisions/ street. It allow to do auto-completion / auto-suggetion
you can
  • Specify one or more words
  • search on part of the name (auto-completion / auto-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, ...

Endpoint

The endpoint is

/fulltext/search?

Example :

https://services.gisgraphy.com/fulltext/fulltextsearch?q=paris

Auto-completion / suggestions

Gisgraphy can provide, via the place search webservice, a very powerful auto completion / suggestion engine. combined with the other parameters of the fulltext engine (latitude, longitude, radius, country code,...), It allows 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 country code 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 us 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 auto-completion, 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.


Parameters

All the parameters are case insensitive and should be encoded in UTF-8 and the URL MUST be encoded.



Here is a summary of the API parameters :


Parameter nameWeb parameter namecomment
q-Required. The searched text : The text for the query can be a zip code, a string or one or more strings
lat-An optional latitude (north-south) for the location point to search around and restrict the search results. The value is a floating number and can be negative. The value is a floating number, between -90 and +90. 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)
lng-An optional longitude (east-west) for the location point to search around and restrict the search results. The value is a floating number between -180 and +180 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). Can be comma or dot separated. example : 3.5 or -42.6
radius10000distance 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.
placetype-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. You can specify more than one placetype http://localhost:8080/fulltext/fulltextsearch?q=paris&placetype=city&placetype=adm
countrylimit the search to the specified ISO 3166 country code. Default : search in all countries
lang-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
allwordsrequiredfalseWhether 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)
fuzzyfalseAllow to do approximative search by correcting missspelled word (not available with auto completion). Can lead to strange results : exact matches can be returned after fuzzy ones. A fuzzy search need a lot of processor and memory and increase the response time.
spellchecking-whether some suggestions should be provided if no results are found. Default value is the value of the 'spellchecker.activeByDefault' option (see more)
suggestfalseIf 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. The JSON format will be forced if this parameter is true. See auto completion / suggestions engine or Gisgraphy leaflet plugin for more detailsfor more details
styleMEDIUMThe 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.
from1The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1.
tofrom + 10The last pagination index. if < 1 or not specified, it will be set to startindex + 10. max = 20
formatXMLOutput formats and languages The following languages are supported :
  • XML
  • JSON
  • PHP
  • Ruby
  • Python
  • YAML
  • GeoRSS
  • ATOM
indentfalseIndents the results. 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.
apikey-The api key (only for premium webservices, useless for local installation)

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


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


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

Output fields description

Here is a description of all the output fields :
FieldDescriptionAvailable from style
errorA String only present if an error occurred (e.g : empty query)
The field 'error' appears in the path response/responseHeader/error
ERROR
feature_idA unique id that identify the featureSHORT
nameThe name of the featureSHORT
scorea number that indicates the relevance of the resultSHORT
fully_qualified_nameA name of the form : (adm1Name et adm2Name are printed) Paris, Département de Ville-De-Paris, Ile-De-France, (FR)SHORT
placetypeThe place Type of the FeatureSHORT
country_codeThe ISO 3166 country codeSHORT
country_nameThe name of the country the features belongs toSHORT
zipcodeThe zipcodesSHORT
google_map_urlRemoved in v 5.0.The URL to get the location on Google MapMEDIUM
openstreetmap_map_urlRemoved in v 5.0.The URL to get the location on OpenStreetMap.orgMEDIUM
yahoo_map_urlRemoved in v 5.0.The URL to get the location on Yahoo MapMEDIUM
one_wayWhether the street is one way or not (only for placetype street)MEDIUM
LengthThe length of the street (only for placetype street)MEDIUM
street_refOptional road (national/international) reference of the streetMEDIUM
lanesnumber of lanes of the streets for this particular segmentMEDIUM
tollWhether some fee must be paid by general traffic to use the street (no value does not mean anything, can be both)MEDIUM
surfaceTell the physical surface of the street (paved, asphalt,...)MEDIUM
max_speedLegal speed limit for general traffic on the forward direction (not side), if only a number stands for km/h, otherwise the unit is to be specified (mph for instance)MEDIUM
speed_modeTells about the way the maxspeed and maxspeedbackward come from. Can be OSM when comes from openstreetmap or CALCULATED when it is based on general consideration as the speed limit in a city)MEDIUM
max_speed_backwardLegal speed limit for general traffic on the backward direction (not side), if only a number stands for km/h, otherwise the unit is to be specified (mph for instance)MEDIUM
azimuth_startNumber in degres of the azimuth (ordinal direction) at the begining of the street (useful for GPS to indicates to take to the north for instance or to calculate the difference between two streets and tell the user to take to the right, left, or to see if a street is a line or not by comparing the difference between the azimuth at the start and at the end, etc)MEDIUM
azimuth_endSee azimuth_startMEDIUM
labelRepresentative label of the street (most often contain the street name and locality)MEDIUM
label_postalLabel as it will be used to mention the streest on an enveloppe or on a postal systemMEDIUM
openstreetmap_idThe OpenStreetMap unique id of the street (only for placetype street)MEDIUM
is_inInformation on the city where the street / POI is (depends on OpenStreetMap 'is_in' field), the city in general (only for placetype street)MEDIUM
is_in_placeInformation on the place where the street / POI is (quater, common place). Generally a place at a lower level than cityMEDIUM
is_in_admInformation of the administration division where the street / POI is.MEDIUM
is_in_zipInformation of the zipcode where the street / POI is (often fill for placetype street)MEDIUM
house_numbersa list of all the house numbers and their coordinates (only for placetype street). house number are sortedMEDIUM
municipalityif the place is a municipality. it is usefull for geonames feature that don't have concept of 'city' but a populated place (that can be a quarter)MEDIUM
amenityInformations on category of OpenStreetMap POIsMEDIUM
street_typeThe type of the street (only for placetype street)MEDIUM
country_flag_urlThe relative URL to get the country flag imageMEDIUM
feature_classThe feature Class. More...MEDIUM
feature_codeThe feature Code. More...MEDIUM
populationHow many people live in this featureMEDIUM
elevationElevation in metersMEDIUM
name_asciiThe ASCII nameMEDIUM
timezoneThe timezone (e.g :Europe/Paris)MEDIUM
gtopo30Average elevation of 30'x30' (ca 900mx900m) area in metersMEDIUM
latThe latitude (north-south)MEDIUM
lngThe longitude (east-West)MEDIUM
continentThe continent the country belongs (only for country placetype)MEDIUM
currency_codeThe ISO 4217 Currency from the curencycode (only for country placetype)MEDIUM
currency_nameThe name of the currency of the country (only for country placetype)MEDIUM
fips_codeThe FIPS Code of the country (only for country placetype)MEDIUM
isoalpha2_country_codeThe ISO 3166 alpha 2 code of the country (only for country placetype)MEDIUM
isoalpha3_country_codeThe ISO 3166 alpha 3 code of the country (only for country placetype)MEDIUM
postal_code_maskThe mask that postal codes should verify. e.g : ##### (only for country placetype)MEDIUM
postal_code_regexThe regular expression that postal codes should verify (only for country placetype)MEDIUM
phone_prefixThe phone prefix of the country. e.g : +33 .(only for country placetype)MEDIUM
spoken_languagesList of languages spoken in the country (only for country placetype)MEDIUM
tldTop level domain of the country (only for country placetype)MEDIUM
capital_nameName of the capital of the country(only for country placetype)MEDIUM
areaArea of the country in m² (only for country placetype)MEDIUM
levelLevel of the Adm 1 , 2, 3, or 4(only for Adm placetype)MEDIUM
adm1_codeRemoved in v 5.0.The internal code for the administrative division of level 1LONG
adm2_code</td>Removed in v 5.0.The internal code for the administrative division of level 2LONG
adm3_codeRemoved in v 5.0.The internal code for the administrative division of level 3LONG
adm4_codeRemoved in v 5.0.The internal code for the administrative division of level 4LONG
adm1_nameThe name of the administrative division of level 1LONG
adm2_nameThe name of the administrative division of level 2LONG
adm3_nameThe name of the administrative division of level 3LONG
adm4_nameThe name of the administrative division of level 4LONG
name_alternateThe alternate names of the feature that without specific language codeLONG
name_alternate_languagecodeThe alternate names of the feature for this language CodeLONG
adm1_name_alternateThe alternate names of the administrative division of level 1 without specific language codeFULL
adm1_name_alternate_languagecodeThe alternatenames of the administrative division of level 1 for this language CodeFULL
adm2_name_alternateThe alternate names of the administrative division of level 2 without specific language codeFULL
adm2_name_alternate_languagecodeThe alternatenames of the administrative division of level 2 for this language CodeFULL
country_name_alternateThe alternate names of the country without specific language codeFULL
country_name_alternate_languagecodeThe alternate names of the country for this language code
, If you specify link as a languagecode, you will get the Wikipedia link
FULL
fullyQualifiedAddressNOT USED YETN/A


Example of feed

Example of feed : https://services.gisgraphy.com/fulltext/fulltextsearch?q=paris&style=full&from=1&to=1 :
<response>
	<lst name="responseHeader">
		<int name="status">0</int>
		<int name="QTime">0</int>
	</lst>
	<result name="response" numFound="70309" start="0" maxScore="6.990118">
		<doc>
			<float name="score">6.990118</float>
			<str name="adm1_name">France métropolitaine</str>
			<arr name="adm1_name_alternate">
				<str>Іль-дэ-Франс</str>
				<str>इल-दा-फ़्रान्स</str>
				<str>Illa de França</str>
				<str>Ilha de França</str>
				<str>Enez-Frañs</str>
				<str>Île-de-France</str>
				<str>ایل-دو-فرانس</str>
				<str>Іль-де-Франс</str>
				<str>Isla de Francia</str>
				<str>Isola di Francia</str>
				<str>Иль-де-Франс</str>
				<str>إيل دو فرانس</str>
				<str>Ile-de-France</str>
				<str>İl de Frans</str>
				<str>일드프랑스</str>
				<str>Insula Franciae</str>
				<str>Illa de França</str>
				<str>Francilio</str>
				<str>איל-דה-פראנס</str>
			</arr>
			<arr name="adm1_name_alternate_AR">
				<str>إيل دو فرانس</str>
			</arr>
			<arr name="adm1_name_alternate_AZ">
				<str>İl de Frans</str>
			</arr>
			<arr name="adm1_name_alternate_BE">
				<str>Іль-дэ-Франс</str>
			</arr>
			<arr name="adm1_name_alternate_BR">
				<str>Enez-Frañs</str>
			</arr>
			<arr name="adm1_name_alternate_CA">
				<str>Illa de França</str>
			</arr>
			<arr name="adm1_name_alternate_EN">
				<str>Ile-de-France</str>
			</arr>
			<arr name="adm1_name_alternate_EO">
				<str>Francilio</str>
			</arr>
			<arr name="adm1_name_alternate_ES">
				<str>Isla de Francia</str>
			</arr>
			<arr name="adm1_name_alternate_EU">
				<str>Île-de-France</str>
			</arr>
			<arr name="adm1_name_alternate_FA">
				<str>ایل-دو-فرانس</str>
			</arr>
			<arr name="adm1_name_alternate_HE">
				<str>איל-דה-פראנס</str>
			</arr>
			<arr name="adm1_name_alternate_HI">
				<str>इल-दा-फ़्रान्स</str>
			</arr>
			<arr name="adm1_name_alternate_IT">
				<str>Isola di Francia</str>
			</arr>
			<arr name="adm1_name_alternate_KO">
				<str>일드프랑스</str>
			</arr>
			<arr name="adm1_name_alternate_LA">
				<str>Insula Franciae</str>
			</arr>
			<arr name="adm1_name_alternate_OC">
				<str>Illa de França</str>
			</arr>
			<arr name="adm1_name_alternate_PT">
				<str>Ilha de França</str>
			</arr>
			<arr name="adm1_name_alternate_RU">
				<str>Иль-де-Франс</str>
			</arr>
			<arr name="adm1_name_alternate_UK">
				<str>Іль-де-Франс</str>
			</arr>
			<str name="adm3_name">Paris</str>
			<str name="adm4_name">Paris</str>
			<str name="country_code">FR</str>
			<str name="country_name">France</str>
			<str name="feature_class">P</str>
			<str name="feature_code">PPLC</str>
			<long name="feature_id">2988507</long>
			<str name="fully_qualified_name">Paris, Île-de-France, France métropolitaine, (75000)
			</str>
			<int name="gtopo30">42</int>
			<str name="label">Paris</str>
			<double name="lat">48.85662441422802</double>
			<double name="lat_admin_centre">48.856610100000005</double>
			<double name="lng">2.3428733119636145</double>
			<double name="lng_admin_centre">2.3514992</double>
			<bool name="municipality">true</bool>
			<str name="name">Paris</str>
			<arr name="name_alternate">
				<str>Париж</str>
				<str>Parys</str>
				<str>პარიზი</str>
				<str>Париж</str>
				<str>Париж</str>
				<str>Parijs</str>
				<str>Baariis</str>
				<str>Palika</str>
				<str>पेरिस</str>
				<str>Párizs</str>
				<str>ប៉ារីស</str>
				<str>Pariis</str>
				<str>Pariz</str>
				<str>París</str>
				<str>Pariggi</str>
				<str>Paris</str>
				<str>Paris</str>
				<str>Париж</str>
				<str>ܦܐܪܝܣ</str>
				<str>Paris</str>
				<str>París</str>
				<str>Paris</str>
				<str>Париж</str>
				<str>Paris</str>
				<str>Lungsod ng Paris</str>
				<str>Pariisi</str>
				<str>Paris</str>
				<str>Pariis</str>
				<str>Παρίσι</str>
				<str>Paris</str>
				<str>Pariž</str>
				<str>పారిస్</str>
				<str>París</str>
				<str>Paris</str>
				<str>Parys</str>
				<str>Paryż</str>
				<str>París</str>
				<str>Paris</str>
				<str>Paris</str>
				<str>Paarys</str>
				<str>Parī</str>
				<str>Parigi</str>
				<str>पैरिस</str>
				<str>Paris</str>
				<str>Paríž</str>
				<str>پاريس</str>
				<str>Paris</str>
				<str>Paris</str>
				<str>Париж</str>
				<str>Paris</str>
				<str>پاریس</str>
				<str>Paris</str>
				<str>Pariggi</str>
				<str>Париж</str>
				<str>Pariz</str>
				<str>Lutetia Parisorum</str>
				<str>Парис</str>
				<str>paris</str>
				<str>Paříž</str>
				<str>Pa-ri</str>
				<str>פאריז</str>
				<str>Pariz</str>
				<str>París</str>
				<str>پاریس</str>
				<str>Paris</str>
				<str>PAR</str>
				<str>Paris</str>
				<str>پیرس</str>
				<str>Париж</str>
				<str>Paris</str>
				<str>Парижь</str>
				<str>Parizo</str>
				<str>Parij</str>
				<str>Paries</str>
				<str>Parîs</str>
				<str>باريس</str>
				<str>Parisi</str>
				<str>ပါရီမြို့</str>
				<str>Париж</str>
				<str>Pariz</str>
				<str>ཕ་རི།</str>
				<str>Париз</str>
				<str>Paname</str>
				<str>ปารีส</str>
				<str>Pari</str>
				<str>巴黎</str>
				<str>ಪ್ಯಾರಿಸ್</str>
				<str>პარიზი</str>
				<str>Parighji</str>
				<str>Париж</str>
				<str>Parĩ</str>
				<str>パリ</str>
				<str>Paryžius</str>
				<str>Bahliz</str>
				<str>پارىژ</str>
				<str>París</str>
				<str>Pantruche</str>
				<str>París</str>
				<str>Lutèce</str>
				<str>París</str>
				<str>Paris</str>
				<str>પૅરિસ</str>
				<str>ፓሪስ</str>
				<str>Paryż</str>
				<str>Горад Парыж</str>
				<str>Paris</str>
				<str>പാരിസ്</str>
				<str>פריז</str>
				<str>Париж</str>
				<str>Париж</str>
				<str>巴黎</str>
				<str>Lutetia</str>
				<str>Páras</str>
				<str>Париж</str>
				<str>ਪੈਰਿਸ</str>
				<str>باريس</str>
				<str>Paris</str>
				<str>Paris</str>
				<str>Pariižu</str>
				<str>Pari</str>
				<str>Paris</str>
				<str>Paris</str>
				<str>Parisi</str>
				<str>Paris</str>
				<str>প্যারিস</str>
				<str>پیرس</str>
				<str>Paris</str>
				<str>Париж ош</str>
				<str>Паріж</str>
				<str>Paris</str>
				<str>Parys</str>
				<str>Париж</str>
				<str>파리</str>
				<str>Париж</str>
				<str>Paris</str>
				<str>پاریس</str>
				<str>Paräis</str>
				<str>Paris</str>
				<str>பாரிஸ்</str>
				<str>Parigi</str>
				<str>Ville-Lumière</str>
				<str>París</str>
				<str>Parîs</str>
				<str>Փարիզ</str>
				<str>Парис</str>
				<str>पॅरिस</str>
				<str>Paris</str>
				<str>Parigge</str>
				<str>Paris</str>
				<str>Parīze</str>
				<str>Parixe</str>
				<str>Paris</str>
				<str>Париз</str>
				<str>Pariz</str>
			</arr>
			<arr name="name_alternate_AF">
				<str>Parys</str>
			</arr>
			<arr name="name_alternate_ALS">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_AM">
				<str>ፓሪስ</str>
			</arr>
			<arr name="name_alternate_AN">
				<str>París</str>
			</arr>
			<arr name="name_alternate_AR">
				<str>باريس</str>
			</arr>
			<arr name="name_alternate_ARC">
				<str>ܦܐܪܝܣ</str>
			</arr>
			<arr name="name_alternate_ARZ">
				<str>باريس</str>
			</arr>
			<arr name="name_alternate_AST">
				<str>París</str>
			</arr>
			<arr name="name_alternate_BA">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_BE">
				<str>Горад Парыж</str>
			</arr>
			<arr name="name_alternate_BG">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_BN">
				<str>প্যারিস</str>
			</arr>
			<arr name="name_alternate_BO">
				<str>ཕ་རི།</str>
			</arr>
			<arr name="name_alternate_BR">
				<str>Pariz</str>
			</arr>
			<arr name="name_alternate_BS">
				<str>Pariz</str>
			</arr>
			<arr name="name_alternate_CA">
				<str>París</str>
			</arr>
			<arr name="name_alternate_CKB">
				<str>پاریس</str>
			</arr>
			<arr name="name_alternate_CO">
				<str>Parighji</str>
			</arr>
			<arr name="name_alternate_CS">
				<str>Paříž</str>
			</arr>
			<arr name="name_alternate_CU">
				<str>Парижь</str>
			</arr>
			<arr name="name_alternate_CV">
				<str>Парис</str>
			</arr>
			<arr name="name_alternate_CY">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_DA">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_DE">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_EL">
				<str>Παρίσι</str>
			</arr>
			<arr name="name_alternate_EN">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_EO">
				<str>Parizo</str>
			</arr>
			<arr name="name_alternate_ES">
				<str>París</str>
			</arr>
			<arr name="name_alternate_ET">
				<str>Pariis</str>
			</arr>
			<arr name="name_alternate_EU">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_EXT">
				<str>París</str>
			</arr>
			<arr name="name_alternate_FA">
				<str>پاریس</str>
			</arr>
			<arr name="name_alternate_FI">
				<str>Pariisi</str>
			</arr>
			<arr name="name_alternate_FR">
				<str>Paris</str>
				<str>Paname</str>
				<str>Pantruche</str>
				<str>Lutèce</str>
				<str>Ville-Lumière</str>
			</arr>
			<arr name="name_alternate_FUR">
				<str>Parîs</str>
			</arr>
			<arr name="name_alternate_FY">
				<str>Parys</str>
			</arr>
			<arr name="name_alternate_GA">
				<str>Páras</str>
			</arr>
			<arr name="name_alternate_GAN">
				<str>巴黎</str>
			</arr>
			<arr name="name_alternate_GD">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_GL">
				<str>París</str>
			</arr>
			<arr name="name_alternate_GN">
				<str>Parĩ</str>
			</arr>
			<arr name="name_alternate_GU">
				<str>પૅરિસ</str>
			</arr>
			<arr name="name_alternate_GV">
				<str>Paarys</str>
			</arr>
			<arr name="name_alternate_HA">
				<str>Pariis</str>
			</arr>
			<arr name="name_alternate_HAW">
				<str>Palika</str>
			</arr>
			<arr name="name_alternate_HBS">
				<str>Pariz</str>
			</arr>
			<arr name="name_alternate_HE">
				<str>פריז</str>
			</arr>
			<arr name="name_alternate_HI">
				<str>पैरिस</str>
			</arr>
			<arr name="name_alternate_HR">
				<str>Pariz</str>
			</arr>
			<arr name="name_alternate_HU">
				<str>Párizs</str>
			</arr>
			<arr name="name_alternate_HY">
				<str>Փարիզ</str>
			</arr>
			<arr name="name_alternate_IA">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_IATA">
				<str>PAR</str>
			</arr>
			<arr name="name_alternate_ID">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_IO">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_IS">
				<str>París</str>
			</arr>
			<arr name="name_alternate_IT">
				<str>Parigi</str>
			</arr>
			<arr name="name_alternate_JA">
				<str>パリ</str>
			</arr>
			<arr name="name_alternate_JBO">
				<str>paris</str>
			</arr>
			<arr name="name_alternate_KA">
				<str>პარიზი</str>
			</arr>
			<arr name="name_alternate_KK">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_KM">
				<str>ប៉ារីស</str>
			</arr>
			<arr name="name_alternate_KN">
				<str>ಪ್ಯಾರಿಸ್</str>
			</arr>
			<arr name="name_alternate_KO">
				<str>파리</str>
			</arr>
			<arr name="name_alternate_KRC">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_KSH">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_KU">
				<str>Parîs</str>
			</arr>
			<arr name="name_alternate_KV">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_KW">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_KY">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_LA">
				<str>Lutetia Parisorum</str>
				<str>Lutetia</str>
			</arr>
			<arr name="name_alternate_LAD">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_LB">
				<str>Paräis</str>
			</arr>
			<arr name="name_alternate_LI">
				<str>Paries</str>
			</arr>
			<arr name="name_alternate_LIJ">
				<str>Pariggi</str>
			</arr>
			<arr name="name_alternate_LMO">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_LN">
				<str>Pari</str>
			</arr>
			<arr name="name_alternate_LT">
				<str>Paryžius</str>
			</arr>
			<arr name="name_alternate_LV">
				<str>Parīze</str>
			</arr>
			<arr name="name_alternate_MG">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_MHR">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_MI">
				<str>Parī</str>
			</arr>
			<arr name="name_alternate_MK">
				<str>Париз</str>
			</arr>
			<arr name="name_alternate_ML">
				<str>പാരിസ്</str>
			</arr>
			<arr name="name_alternate_MN">
				<str>Парис</str>
			</arr>
			<arr name="name_alternate_MR">
				<str>पॅरिस</str>
			</arr>
			<arr name="name_alternate_MRJ">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_MS">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_MY">
				<str>ပါရီမြို့</str>
			</arr>
			<arr name="name_alternate_MYV">
				<str>Париж ош</str>
			</arr>
			<arr name="name_alternate_MZN">
				<str>پاریس</str>
			</arr>
			<arr name="name_alternate_NA">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_NAP">
				<str>Parigge</str>
			</arr>
			<arr name="name_alternate_NDS">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_NE">
				<str>पेरिस</str>
			</arr>
			<arr name="name_alternate_NL">
				<str>Parijs</str>
			</arr>
			<arr name="name_alternate_NN">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_NO">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_OC">
				<str>París</str>
			</arr>
			<arr name="name_alternate_OLO">
				<str>Pariižu</str>
			</arr>
			<arr name="name_alternate_OS">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_PA">
				<str>ਪੈਰਿਸ</str>
			</arr>
			<arr name="name_alternate_PL">
				<str>Paryż</str>
			</arr>
			<arr name="name_alternate_PMS">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_PNB">
				<str>پیرس</str>
			</arr>
			<arr name="name_alternate_PS">
				<str>پاريس</str>
			</arr>
			<arr name="name_alternate_PT">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_RO">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_RU">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_RUE">
				<str>Паріж</str>
			</arr>
			<arr name="name_alternate_SAH">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_SC">
				<str>Parigi</str>
			</arr>
			<arr name="name_alternate_SCN">
				<str>Pariggi</str>
			</arr>
			<arr name="name_alternate_SCO">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_SK">
				<str>Paríž</str>
			</arr>
			<arr name="name_alternate_SL">
				<str>Pariz</str>
			</arr>
			<arr name="name_alternate_SO">
				<str>Baariis</str>
			</arr>
			<arr name="name_alternate_SQ">
				<str>Paris</str>
				<str>Parisi</str>
			</arr>
			<arr name="name_alternate_SR">
				<str>Париз</str>
			</arr>
			<arr name="name_alternate_SV">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_SW">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_SZL">
				<str>Paryż</str>
			</arr>
			<arr name="name_alternate_TA">
				<str>பாரிஸ்</str>
			</arr>
			<arr name="name_alternate_TE">
				<str>పారిస్</str>
			</arr>
			<arr name="name_alternate_TET">
				<str>París</str>
			</arr>
			<arr name="name_alternate_TG">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_TH">
				<str>ปารีส</str>
			</arr>
			<arr name="name_alternate_TK">
				<str>Pariž</str>
			</arr>
			<arr name="name_alternate_TL">
				<str>Paris</str>
				<str>Lungsod ng Paris</str>
			</arr>
			<arr name="name_alternate_TR">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_TT">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_TY">
				<str>Paris</str>
			</arr>
			<arr name="name_alternate_UDM">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_UG">
				<str>پارىژ</str>
			</arr>
			<arr name="name_alternate_UK">
				<str>Париж</str>
			</arr>
			<arr name="name_alternate_UR">
				<str>پیرس</str>
			</arr>
			<arr name="name_alternate_UZ">
				<str>Parij</str>
			</arr>
			<arr name="name_alternate_VEC">
				<str>Parixe</str>
			</arr>
			<arr name="name_alternate_VI">
				<str>Paris</str>
				<str>Pa-ri</str>
			</arr>
			<arr name="name_alternate_VLS">
				<str>Parys</str>
			</arr>
			<arr name="name_alternate_WO">
				<str>Pari</str>
			</arr>
			<arr name="name_alternate_XMF">
				<str>პარიზი</str>
			</arr>
			<arr name="name_alternate_YI">
				<str>פאריז</str>
			</arr>
			<arr name="name_alternate_YO">
				<str>Parisi</str>
			</arr>
			<arr name="name_alternate_ZA">
				<str>Bahliz</str>
			</arr>
			<arr name="name_alternate_ZH">
				<str>巴黎</str>
			</arr>
			<str name="name_ascii">Paris</str>
			<long name="openstreetmap_id">7444</long>
			<str name="placetype">City</str>
			<int name="population">2243833</int>
			<str name="timezone">Europe/Paris</str>
			<arr name="zipcode">
				<str>75009</str>
				<str>75008</str>
				<str>75019</str>
				<str>75007</str>
				<str>75018</str>
				<str>75006</str>
				<str>75017</str>
				<str>75116</str>
				<str>75005</str>
				<str>75016</str>
				<str>75004</str>
				<str>75015</str>
				<str>75003</str>
				<str>75014</str>
				<str>75002</str>
				<str>75013</str>
				<str>75001</str>
				<str>75012</str>
				<str>75000</str>
				<str>75011</str>
				<str>75010</str>
				<str>75020</str>
				<str>78116</str>
			</arr>
		</doc>
	</result>
	<lst name="spellcheck">
		<lst name="suggestions" />
	</lst>
	<lst name="attributions">
		<str name="attribution">http://www.gisgraphy.com/attributions.html</str>
	</lst>
</response>


Java API

The fulltext API looks like this
	Pagination pagination = paginate().from(STARTINDEX).to(ENDINDEX);
	Output output = Output.withFormat(OUTPUTFORMAT)
			.withLanguageCode(LANGUAGECODE).withStyle(VERBOSITY)
			.WithIndentation();
			
	FulltextQuery fulltextQuery = new FulltextQuery("SEARCHEDTEXT",
			pagination, output, PLACETYPE.class, COUNTRYCODE);
			fulltextQuery.withAllWordsRequired(true)
			.around(POINT)
			.withRadius(RADIUS).limitToCountryCode("FR");
	String result = fullTextSearchEngine.executeQueryToString(fulltextQuery);
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);


The API is thread safe.


Nearby service

Description


The nearby / geolocalisation service allows to search for features / place around a GPS location.
you can
  • Specify GPS position
  • Limit the results to a specific place type (e.g : search all restaurant 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)

Endpoint

The endpoint is

/geoloc/search?

Example :

https://services.gisgraphy.com/geoloc/search?lat=48.8&lng=2.5&radius=7000&placetype=restaurant

Parameters

All the parameters are case insensitive and should be encoded in UTF-8 and the URL MUST be encoded.



Here is a summary of the API parameters :

ParameterDefaultDescription
Latitude-Required. 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. Can be comma or point separated. Examples : 3.5 or 3,5
Longitude-Required. 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. Can be comma or point separated. (see also 'lat' parameter). Examples : 3.5 or 3,5
radius10000The 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).
placetype-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. See a full list and explanation of placetype : here. You can specify only one placetype per request
distancetrueDistance field : Whether (or not) we want the distance field to be output. 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".
formatXMLOutput formats and languages The following languages are supported :
  • XML
  • JSON
  • PHP
  • Ruby
  • Python
  • YAML
from1The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1.
tofrom + 10The last pagination index. if < 1 or not specified, it will be set to startindex + 10. max = 20
callback-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)
indentfalseIndents the results. 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".
apikey-The 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 place type (e.g : area is only available if the feature is a country) :

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


Example of feed

Example of feed : https://services.gisgraphy.com/geoloc/search?lat=48.8&lng=2.5&radius=7000&placetype=restaurant :
<results xmlns="http://gisgraphy.com">
	<numFound>1</numFound>
	<QTime>60</QTime>
	<attributions>http://www.gisgraphy.com/attributions.html</attributions>
	<result>
		<distance>107.00647498</distance>
		<name>Au Palmier II</name>
		<label>Au Palmier II, Saint-Maur-des-Fossés</label>
		<countryCode>FR</countryCode>
		<featureClass>UNK</featureClass>
		<featureCode>UNK</featureCode>
		<featureId>27209504</featureId>
		<population>75402</population>
		<lat>48.7990761</lat>
		<lng>2.4995873</lng>
		<placeType>gisfeature</placeType>
		<openstreetmapId>738812921</openstreetmapId>
		<google_map_url>https://www.google.fr/maps/preview#!q=48.8290761+2.4995873
		</google_map_url>
		<yahoo_map_url>http://maps.yahoo.com/place/?lat=48.7990761&amp;amp;lon=2.4995873
		</yahoo_map_url>
		<openstreetmap_map_url>http://www.openstreetmap.org/#map=14/48.7990761/2.4995873
		</openstreetmap_map_url>
		<country_flag_url>/images/flags/FR.png</country_flag_url>
		<isIn>Saint-Maur-des-Fossés</isIn>
		<isInAdm>Créteil</isInAdm>
		<amenity>restaurant</amenity>
		<fullyQualifiedName>Au Palmier II, Saint-Maur-des-Fossés
		</fullyQualifiedName>
		<zipCode>94100</zipCode>
	</result>
</results>

Java API

The geoloc API looks like this
	Point point = GeolocHelper.createPoint(LONGITUDE, LATITUDE);
	Pagination pagination = paginate().from(STARTINDEX).to(ENDINDEX);
	Output output = Output.withFormat(OUTPUTFORMAT)
						  .WithIndentation();
	GeolocQuery query = new GeolocQuery(point,RADIUS,pagination,output,PLACETYPE.class);
	String results = geolocSearchEngine.executeQueryToString(query);
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 API is thread safe.

Client libraries

Client libraries exist 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 :
userpasswordprofileDescription
useruserROLE_USERuser with simple rights : can not admin other users, can only edit his profile, can not import data
adminadminROLE_ADMINuser with all rights : can admin other users and profiles, can edit options,can import data.

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

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 1 month, depending on how much data you import and the machine the importer runs on. You can order some dumps to avoid loooong import.

Add / edit data

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

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'

Performance

Jmeter

Some Jmeter benchmarks are available (scripts and results) here. You can also read the relevance and performance page


Database Optimisation

To have good performance. you have to create PostgreSQL indexes by running the scripts provided in the SQL directory of the Gisgraphy distribution



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

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

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