Geocoding API

Learn to generate geographical coordinates with a location name and vice versa.

We'll cover the following

Geocoding API allows users to search for locations using their names and geographical coordinates. Geographical coordinates allow for a location to be specified accurately. This API is particularly useful in cases where the user may require the geographical coordinates for a given location or the location’s name given some geographical coordinates.

Geocoding refers to the translation of any geographical location name to its corresponding geographical coordinates—latitude and longitude. The reverse of this process—to get the name of a location from its geographical coordinates—is called reverse geocoding. We can use the geocoding API to perform both operations for different cities, areas, districts, states, and countries.

Direct geocoding

Direct geocoding is the process of getting geographical coordinates of a given location by specifying its name. For this purpose, we use the following URI:

http://api.openweathermap.org/geo/1.0/direct?q={city name},{state code},{country code}&appid={APP_ID}

Request parameters

Parameter

Type

Category

Description

APP_ID

string

required

This is our unique API key.

q

string

required

This can either be the city name only or the city name followed by the state and country codes, separated by commas.

limit

integer

optional

This is the number of locations to retrieve. Its maximum value is 5.

Note:

  • Make sure that the location specified using the q parameter is one of the registered 200,000+ locations.

  • We can search for locations within the USA by specifying the state. This option is not available for locations outside of the USA.

  • For state codes and country codes, refer to ISO 3166.

  • In case there are multiple locations with the same name, we can use the limit parameter to specify the number of locations to retrieve.

Lines 16–17: We enter Seattle, Washington, US for the required parameter q. We also add an additional optional parameter, limit, with the value of 1 to retrieve the top location from the results.

Click the "Run" button in the widget below to see the output.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define APP ID here
const APP_ID = '{{APP_ID}}';
// Define endpoint URL here
const url = new URL(`http://api.openweathermap.org/geo/1.0/direct`);
// Define header parameters here
const headerParameters = {
  contentType: 'application/json',
};
// Define query parameters here
const q = 'Seattle, Washington, US';
const limit = 1;
const queryParameters = new URLSearchParams({
  q: q,
  limit: limit.toString(),
  appid: APP_ID
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function getLocations() {
  try {
    url.search = queryParameters;
    const response = await fetch(url, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
 
// Calling function to make API call
getLocations();

Let's take a quick look at the code given in the widget above:

  • Line 8: We define the URL for the current weather data endpoint.

  • Lines 19–23: We define the query parameters for the direct geocoding endpoint.

  • Lines 32–43: We define a custom function getLocations() to make an API call using fetch and handle any exception if it occurs. The printResponse() and printError() are custom functions to print the API response and errors, respectively.

  • Line 46: We invoke the getLocations() function.

The code above displays the location name and the geographical coordinates for the specified location.

Response fields

Let's look into the response fields generated by this endpoint.

Parameter

Type

Description

name

string

This is the location's name.

state

string

This is the state corresponding to the location. Its value may be NULL.

country

string

This is the country corresponding to the location.

lat

decimal

This is the location’s latitude.

lon

decimal

This is the location’s longitude.

local_names.[language code]

string

This is the list of location's names in various languages. This list could vary for different locations.

local_names.ascii

string

This is an internal field.

local_names.feature_name

string

This is an internal field.

Note: The fields in the API response vary based on the location and the country to which a location belongs.

Reverse geocoding

Reverse geocoding is the process of getting the name of a location by specifying its geographical coordinates. In this case, we use the following URI:

http://api.openweathermap.org/geo/1.0/reverse?lat={lat}&lon={lon}&appid={APP_ID}

Request parameters

Parameter

Type

Category

Description

APP_ID

string

required

This is our unique API key.

lat

decimal

required

This refers to the geographical coordinate, latitude, of a given location.

lon

decimal

required

This refers to the geographical coordinate, longitude, of a given location.

limit

integer

optional

This is the number of locations to retrieve. Its maximum value is 5.

Note: In case there are multiple locations with the same name, we can use the limit parameter to specify the number of locations to retrieve.

Lines 16–18: We enter 47.6038321 and -122.3300624, the geographical coordinates for Seattle, United States, for the required parameters lat and lon, respectively. We also add an additional optional parameter, limit, with the value of 1 to retrieve the top location from the results.

Click the "Run" button in the widget below to see the output.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define APP ID here
const APP_ID = '{{APP_ID}}';
// Define endpoint URL here
const url = new URL(`http://api.openweathermap.org/geo/1.0/reverse`);
// Define header parameters here
const headerParameters = {
  contentType: 'application/json',
};
// Define query parameters here
const lat = 47.6038321;
const lon = -122.3300624;
const limit = 1;
const queryParameters = new URLSearchParams({
  lat: lat.toString(),
  lon: lon.toString(),
  limit: limit.toString(),
  appid: APP_ID
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function getLocations() {
  try {
    url.search = queryParameters;
    const response = await fetch(url, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
 
// Calling function to make API call
getLocations();

Let's take a quick look at the code given in the widget above:

  • Line 8: We define the URL for the current weather data endpoint.

  • Lines 20–25: We define the query parameters for the reverse geocoding endpoint.

  • Lines 34–45: We define a custom function getLocations() to make an API call using fetch and handle any exception if it occurs. The printResponse() and printError() are custom functions to print the API response and errors, respectively.

  • Line 48: We invoke the getLocations() function.

The code above displays the location name and the geographical coordinates for the specified location.

Response fields

Let's look into the response fields generated by this endpoint.

Parameter

Type

Description

name

string

This is the location's name.

state

string

This is the state corresponding to the location. Its value may be NULL.

country

string

This is the country corresponding to the location.

lat

decimal

This is the location’s latitude.

lon

decimal

This is the location’s longitude.

local_names.[language code]

string

This is the list of location's names in various languages. This list could vary for different locations.

local_names.ascii

string

This is an internal field.

local_names.feature_name

string

This is an internal field.

Note: The fields in the API response vary based on the location and the country to which a location belongs.