Reverse Geocoding library for Java

I’ve written a small Java library, which is basically a wrap-around for Nominatim, a reverse geocoding [which means the input is a position given by latitude and longitude and the output is a street address] service based on OpenStreetMap. You can use it as library in your own projects or as command line tool.

Command line

Necessary parameters are -lat and -lon for latitude and longitude. The simplest possible call looks like this:

 java -jar reverseGeocoding.jar -lat 57.1653392 -lon -2.1056118

and the result will look like this:

Sir Duncan Rice Library, Bedford Road, Kittybrewster, Aberdeen, Aberdeen City, S cotland, AB24 3AA, United Kingdom

There are two optional parameters: With -zoom and a number between 0 and 18 you can select the level of detail of the result, where 0 means only the country will be returned and 18 means the full address, including building name or street number, will be returned. The second parameter is -osm, which will add the OpenStreetMap ID and type of the returned entity to the result.


If you want to use it as a library, just add it to your project and use it like this:

NominatimReverseGeocodingJAPI nominatim1 = new NominatimReverseGeocodingJAPI(); //create instance with default zoom level (18)

NominatimReverseGeocodingJAPI nominatim2 = new NominatimReverseGeocodingJAPI(zoom); //create instance with given zoom level

nominatim1.getAdress(lat, lon); //returns Address object for the given position

An Address object has the following get-methods:

  • getOsmId
  • getOsmType
  • getLod
  • getCountryCode
  • getCountry
  • getPostcode
  • getState
  • getCounty
  • getCity
  • getSuburb
  • getRoad
  • getDisplayName

You can change the used Nominatim server by changing the NominatimInstance constant. For more information about Nominatim, usage policy, other servers and how to host your own server, visit the official Nominatim page.

The library is available as jar-file or source code, released under the Apache License 2.0.

  1. Daniel Reyes

    Great!!! Easy and nice!!!
    Thank you very much!!! : )))

  2. Mike Lee

    A true rarity – simple but powerful! I’m already starting to think of ways I can implement this. Many thanks.

  3. Can I find this library on mvn respositories?

  4. bhuvan

    i need the speed limits of road,please can you tell me how to get the speed limit from this library..
    thanks in advance

    • You can’t with nominatim alone. But you can use the OSM ID to query the OSM API and get the speed limit.

  5. Franz-Josef Behr

    Basically very interesting (fo reducation). But I get an HTTP response code: 403. Any idea, Daniel?

    • The http endpoint of the nominatim instance was closed, I updated the code to the https endpoint, if you download the latest version from above it should work again.

  6. Mike Lee

    Franz – It has worked since late February 2018, don’t know why. Was nice while it lasted!

    • The http endpoint of the nominatim instance was closed, I updated the code to the https endpoint, if you download the latest version from above it should work again.

  7. Giorgio Battistoni

    Many thanks, it works perfectly!

  8. Guillaume Blanc

    Awesome work, you have to change getCity to getTown in the Address class to be able to get the town name.
    It lokks like the Json tag has been modified for this field.

    example :

  9. Guillaume Blanc

    Actually the tag change with the location, I did this change in Address :
    if (addressObject.has(„city“)) {
    city= addressObject.getString(„town“);
    if (city.isEmpty() && addressObject.has(„city“)) {
    city = addressObject.getString(„city“);
    if (city.isEmpty() && addressObject.has(„village“)) {
    city= addressObject.getString(„village“);
    if (city.isEmpty() && addressObject.has(„hamlet“)) {
    city= addressObject.getString(„hamlet“);
    if (city.isEmpty() && addressObject.has(„suburb“)) {
    city= addressObject.getString(„suburb“);

    it look s ok.

  10. Mohammad

    This project is amazing! thank you very much sir