Java Geocoding Tutorial

This is a tutorial for using the OpenCage geocoding API in Java.

Topics covered in this tutorial

The code examples below will use your geocoding API key once you log in.

Before we dive in to the tutorial

  1. Sign up for an OpenCage geocoding API key.
  2. Play with the demo page, so that you see the actual response the API returns.
  3. Browse the API reference, so you understand the optional parameters, best practices, possible response codes, and the rate limiting on free trial accounts.

Add JOpenCage as a dependency to your maven or gradle project

Following the library's usage instructions

Reverse (coordinates to address) Example

Send a coordinate pair (latitude, longitude) and receive an address

JOpenCageGeocoder jOpenCageGeocoder = new JOpenCageGeocoder("YOUR-API-KEY");

JOpenCageReverseRequest request = new JOpenCageReverseRequest(41.40015, 2.15765);
request.setLanguage("es"); // show results in a specific language using an IETF format language code
request.setLimit(5); // only return the first 5 results (default is 10)
request.setNoAnnotations(true); // exclude additional info such as calling code, timezone, and currency
request.setMinConfidence(3); // restrict to results with a confidence rating of at least 3 (out of 10)

JOpenCageResponse response = jOpenCageGeocoder.reverse(request);

// get the formatted address of the first result:
String formattedAddress = response.getResults().get(0).getFormatted();
// formattedAddress is now 'Travessera de Gràcia, 142, 08012 Barcelona, España'

Forward (address to coordinates) Example

Send an address and receive a coordinate pair. Format your address according to the steps laid out in our guide to query formatting.

JOpenCageGeocoder jOpenCageGeocoder = new JOpenCageGeocoder("YOUR-API-KEY");
JOpenCageForwardRequest request = new JOpenCageForwardRequest("375 Albert Rd, Woodstock, Cape Town, 7915, South Africa");
request.setRestrictToCountryCode("za"); // restrict results to a specific country
request.setBounds(18.367, -34.109, 18.770, -33.704); // restrict results to a geographic bounding box (southWestLng, southWestLat, northEastLng, northEastLat)

JOpenCageResponse response = jOpenCageGeocoder.forward(request);
JOpenCageLatLng firstResultLatLng = response.getFirstPosition(); // get the coordinate pair of the first result
System.out.println(firstResultLatLng.getLat().toString() + "," + firstResultLatLng.getLng().toString());
// prints -33.9275623,18.4571101

Batch Geocode a List of Addresses from a File

This example is for forward geocoding a list of addresses; the process to reverse geocode a list of coordinate pairs would be similar. Start with a text file of addresses formatted according to the steps laid out in our guide to query formatting.

// myAddresses.txt
25 Queen Victoria St, Gardens, Cape Town, 8001, South Africa
Via Giuseppe Garibaldi, 183, 16032 Camogli GE, Italy
1 Hacker Way, Menlo Park, CA 94025, USA
Iguazu National Park, Brazil
Stanford, 7210, South Africa

// Read the file and geocode the addresses:
JOpenCageGeocoder jOpenCageGeocoder = new JOpenCageGeocoder("YOUR-API-KEY");

InputStream inputFile = getClass().getClassLoader().getResourceAsStream("myAddresses.txt");

List<String> listOfAddresses = new ArrayList<>();
try (BufferedReader br = new BufferedReader(new InputStreamReader(inputFile, StandardCharsets.UTF_8))) {
  listOfAddresses = br.lines().collect(Collectors.toList());
} catch (IOException e) {
  System.out.println("Unable to read file");

System.out.println("Latitude, Longitude:");
for (String address : listOfAddresses) {
  JOpenCageForwardRequest request = new JOpenCageForwardRequest(address);
  JOpenCageResponse response = this.jOpenCageGeocoder.forward(request);

  if (response != null && response.getResults() != null && !response.getResults().isEmpty()) {
    JOpenCageLatLng coordinates = response.getResults().get(0).getGeometry();
    System.out.println(coordinates.getLat().toString() + "," + coordinates.getLng().toString());
  } else {
    System.out.println("Unable to geocode input address: " + address);

  try {
    Thread.sleep(1000); // free trial accounts limited to 1 request/sec
  } catch (InterruptedException e) {

Error handling

In the case of an error, an appropriate error message will be logged, such as:
  • 400: "Invalid request (bad request; a required parameter is missing)!"
  • 401: "Invalid or missing API key!"
  • 402: "Valid request but quota exceeded (payment required)!"
  • 403: "Forbidden. API key blocked"

Start your free trial

2,500 geocoding API requests per day.

No credit card required.