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 formatInstallation
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
Example :
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 :
Parameter | Default | Description |
---|---|---|
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 |
radius | 10000 | Radius in meters. Search around a GPS point and get nearest results first, or search in a bounding box
|
fuzzy | false | Allow 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 |
- | This has been removed since Gisgraphy v 5.0 | |
limitnbresult | 10 | Limits 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) |
format | XML | Output formats and languages
The following languages are supported :
|
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&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 :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 |
id | Unique identifier (but not stable, change at each import of data) of the address | 561364654 | N/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 results | Saint Bartus | |
lat | The 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 | |
sourceId | Reference in the original dataset (e.g : the geonames id or openstreetmap one) | Saint Bartus | |
name | Name of the place (and not the name of people that live at the address) | restaurant Mac Fidle | |
zipCode | The zip or post code | 98104 | 100 MAIN ST POB 1022 SEATTLE WA 98104 |
adm1Name | Name of the first administrative division (the biggest) | California | |
adm2Name | Name of the second administrative division | Clark County | |
adm3Name | Name of the third administrative division | ||
adm4Name | Name of the fourth administrative division | ||
adm5Name | Name of the fifth administrative division | ||
streetRef | Road (national/international) reference of the street | A25 / E 42 | |
Quarter | Quater where the address is | Saint Bartus | |
state | Biggest administrative division | Saint Bartus | |
formatedFull | Fully qualified address with all the admXnames and zip | ||
formatedPostal | Address as it should be written on an envelop (no waranty) | ||
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 |
civicNumberSuffix | The number that follows the house number (Canada only) | 1/2 | 10-123 1/2 main street NW MONTREAL QC H3Z 2Y7 |
country | The country name | USA United States France | Paris - France |
countrycode | The countrycode given in the request | FR 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 thisIGeocodingService 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
Example :
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 :
Parameter | Default | Description |
---|---|---|
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) |
format | XML | Output formats and languages
The following languages are supported :
|
indent | false | 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) |
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 | |
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) | |
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 | |
id | unique identifier (but not stable, change at each import of data) of the address | |
name | name of the place (and not the name of people that live at the address) | |
adm1Name | name of the first administrative division (the biggest) | |
adm2Name | name of the second administrative division | |
adm3Name | name of the third administrative division | |
adm4Name | name of the fourth administrative division | |
adm5Name | name of the fifth administrative division (the smallest) | |
lat_admin_centre | the latitude of the administrative center (not the geometrique one) | |
lng_admin_centre | the longitude of the administrative center (not the geometrique one) | |
formatedFull | fully qualified address with all the admXnames and zip | |
formatedPostal | Address as it should be written on an envelop (no waranty) | |
surface | tell the physical surface of the street (paved, asphalt,...) | |
speedMode | tells 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) | |
maxSpeed | legal 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) | |
maxSpeedBackward | legal 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) | |
azimuthStart | number 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) | |
azimuthEnd | number in degres of the azimuth (ordinal direction) at the end of the street (see bellow) | |
length | length of the segment (a street can be composed of several segment) of the street (in meter) | |
oneWay | tells wether the street is a oneway street or not (no value does not mean anything, can be both) | |
sourceId | reference in the original dataset (e.g : the geonames id or openstreetmap one | |
lanes | number of lanes of the streets for this particular segment | |
toll | whether some fee must be paid by general traffic to use the street (no value does not mean anything, can be both) | |
streetRef | road (national/international) reference of the street | |
countryCode | The 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 thisPoint 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
Example :
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 :
Parameter | Default | Description |
---|---|---|
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 |
radius | 10000 | 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). |
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. |
oneway | false | whether 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 |
distance | true | Distance 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". |
from | 1 | 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. |
to | from+10 | 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) |
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) |
format | XML | Output formats and languages
The following languages are supported :
|
indent | false | 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 web services, useless for local installation) |
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, :Field | Default | Description |
---|---|---|
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) | |
lat | The latitude of the middle of the street(north-south) | |
lng | The longitude of the middle of the street(east-west) | |
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 | |
countryCode | The 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 thisPoint 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);
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
- Language
- Country
- place type
- Paginate the results
- Specify the output verbosity
- Tells if you want the output to be indented
- Tells that all words are required or not
Endpoint
The endpoint is
Example :
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 name | Web parameter name | comment |
---|---|---|
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 |
radius | 10000 | 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. |
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 |
country | limit 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') :
|
allwordsrequired | false | 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) |
fuzzy | false | Allow 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) |
suggest | false | 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. 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 |
style | MEDIUM | The output style verbosity (optional) : Determines the output verbosity. 4 styles are available :
|
from | 1 | The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1. |
to | from + 10 | The last pagination index. if < 1 or not specified, it will be set to startindex + 10. max = 20 |
format | XML | Output formats and languages
The following languages are supported :
|
indent | false | Indents 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 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 :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 |
Removed in v 5.0. | MEDIUM | |
Removed in v 5.0. | MEDIUM | |
Removed in v 5.0. | 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 |
street_ref | Optional road (national/international) reference of the street | MEDIUM |
lanes | number of lanes of the streets for this particular segment | MEDIUM |
toll | Whether some fee must be paid by general traffic to use the street (no value does not mean anything, can be both) | MEDIUM |
surface | Tell the physical surface of the street (paved, asphalt,...) | MEDIUM |
max_speed | Legal 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_mode | Tells 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_backward | Legal 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_start | Number 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_end | See azimuth_start | MEDIUM |
label | Representative label of the street (most often contain the street name and locality) | MEDIUM |
label_postal | Label as it will be used to mention the streest on an enveloppe or on a postal system | 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 |
Removed in v 5.0. | LONG | |
Removed in v 5.0. | LONG | |
Removed in v 5.0. | LONG | |
Removed in v 5.0. | 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 |
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 thisPagination 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);
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
Example :
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 | Default | Description |
---|---|---|
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 |
radius | 10000 | 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). |
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 |
distance | true | Distance 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". |
format | XML | Output formats and languages
The following languages are supported :
|
from | 1 | The first pagination index. Numbered from 1. If the number is < 1 or not specified, it will be set to the default value : 1. |
to | from + 10 | The 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) |
indent | false | 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) |
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
/geoloc
pattern but you can change it in the WEB-INF/web.xmlOutput 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) :
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 |
Removed in v 5.0 since it can be calculated with the countrycode : http://services.gisgraphy.com/images/flags/COUNTRYCODE.png | 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 |
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;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 thisPoint 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);
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 pageAdmin Interface
To access the admin interface :- Launch Gisgraphy
- Open a web browser and go to http://localhost:8080/mainMenu.html
Login - Password
You can insert the two default users with the provided script in the sql directory : insert_users.sql
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. |
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.
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
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
It is recommended to run :
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,...)