Quick start

Does Gisgraphy fit my needs ?

Good question :) You're lost, you're unsure as to what web service to use ? Don't panic :) Here are some case studies that will probably help you! All case studies are not for a specific language or framework; you can do them with your favorite framework or language, in Java, PHP, Ruby, Python, in a browser with JSON, or anything else, because XML is readable by almost any language.

Case Studies :

  • You have a list of hotels (or anything else, e.g shops,...) and you want to offer the possibility to get the nearest(s) hotel(s) from a given GPS position : Solution : Add your own hotels via the web admin interface (a list of hotels is already included in GeoNames but you can add / edit yours), then simply call the find nearby service with the GPS position (and an optional radius) and specify the POIs category to 'hotel'. Note that you can add your own POIs category, but the POIs categories already available are, most often, enough. (see example)
  • You still have a list of places and want to get the nearest(s) from a given address : Call the geocoder to get the GPS position of the address and then call the find nearby. (see example)
  • A user to enter a ZIPcode and you want to display a drop down menu if there is more than one city corresponding to that zip code : Use the full-text engine and restrict the POIs category to city and / or citySubdivision. (see example)
  • You are a trip advisor and want to propose some travels for a given destination : Use the full-text engine to search for city, state, country, lake, mountains, and so on. Many facilities are offered : spell checker, all words required or not, pagination, place type, GPS position, spoken language, or country restriction. A lot of information is available. (see the example)
  • You want to display in real time the name of the street where a given user is (and a list of streets around) : Use the street service to get the nearest streets for a given GPS position. (see example)
  • You have a real estate agency and want to offer a web form with streets auto-completion Use the street service to get a list of streets that contains the given sentence. (see example)
  • You want to parse an address (as string) to extract the useful information and then use it in a specific way Use the address parser service to get individual component parts : house number, street type (bd, street, ..), street name, unit (apt, building, ...), ZIPcode, state, country, city. (see example)

Web service functionalities matrix

You're lost between all the webservices ? They seem to all do the same things ? Not at all, they all have their own role. Choosing the right web service for the right use will give you the best performance and user experience. Here is a matrix that will help you to choose the right webservice for the right needs.

Webservice Given What it's for / What it's not
Geocoding An address, city or street
  • Get GPS location, city and street for the given address, fuzzy search, location bias,fuzzy...
  • If you want to search for other places than city, street or address, please use full-text web service
Reverse geocoding GPS position
  • Find an address and the distance from a GPS point
  • To the house level, if information available
Street search GPS position and partial street name (optional)
  • Find streets and the distance around a given GPS , restrict search to streets that contains the given partial name (useful for auto-completion)
  • Equivalent to find nearby webservice with POIs category = street, but more specific (you can restrict search to one-way/two-way, street type,...)
  • If you want to search for streets in full-text mode, please use the full-text webservice
Address parser A well formed address
  • Divides a single address string into its individual component parts : house number, street type (bd, street, ..), street name, unit (apt, building, ...), ZIPcode, state, country, city, ...
  • If the address is not a normalized address, please use the Geocoding service
Find nearby GPS, a POIs category (optional) and a radius (optional)
  • Find places of the given POIs category and the distance to the given GPS point for the given radius
Full-text A user given string, a GPS point (optional), one or more POIs categories (optional)
  • important : This webservice searches for places (a street or a city or a state or a POIs category) while geocoding service specializes in addresses (a combination of house street city, state)
  • Find plenty of information for a place of the given POIs categories
  • Autocompletion auto suggestions
  • (optional), in several languages, fuzzy search, in full-text mode, restrict search around the given point (optional), in a bounding box or location bias
  • You can set 'allwordsrequired' option to false if you want a more permissive search, or find a place in a sentence


Want to try it before installing? Find some examples of URLs with free access.
Want to have some examples on how to use the services? Go to the demo site
Compare the relevance with other providers. We've got nothing to hide.


Don't want to install it by yourself or want hosted web service? We have hosted solutions! Go to the premium page


Downloads ? yes! but what ?


Consult the installation guide to see how to run Gisgraphy off-line on your servers. You can install it classically or with docker


Go to the documentation page


All you need is in the developer guide. Consult the Github page

Yet an other Geocoder ?

Yes And No :) Gisgraphy has a different philosophy : An Address is not a string ! After more than 11 years of doing geocoding, that's our conclusion : An address is not a string ! it is the cardinality of all of the possible names of the different parts : '3355 S Las Vegas Blvd, Las Vegas ' and 'the Venitian, The Strip NV 89109 USA' are the same address but there is no common word between the two addresses Gisgraphy has its own importer and mixes the bests open source gazeteers / databases such as OpenStreetMap of course, but also Openaddresses, GeoNames, and Quattroshapes, and it transforms them into an address and POI database. it links each house to its street, each street to its city/ZIPcode, and each city to its administrative divisions. All of them are associated with alternate names. Gisgraphy has a different philosophy than the other geocoders. It uses a full-text engine with an address parser to separate the several parts of the address. Then it is simpler to do geocoding and remove ambiguity : streets that have city names, unit information that can disturb the full-text search, house numbers that looks like ZIPcodes,... to have better relevance it use the shapes when possible, it avoids putting a street in a city such that its center is closer than the center of the city it belongs. ...Read more

Do you want to go a little bit further? First, if you haven't read it yet, please read the short web services descriptions on the home page or consult the web service functionalities matrix. It will give you a good overview. Then you will find several sections that will help you to start.