Geocoding & Reverse Geocoding API Docs

Overview

The Geocoding API provides both forward and reverse geocoding with structured address components. Submit an address to receive precise latitude/longitude coordinates, or submit coordinates to receive a formatted address with city, state, postal code, and country details.

Forward geocoding: address → coordinates
Reverse geocoding: coordinates → address
Structured address components (city, state, zip, country)
Batch processing support for high-volume workflows

Authentication

All API requests require a RapidAPI key passed via the request header. Subscribe to any plan on RapidAPI to receive your API key.

Header
X-RapidAPI-Key: your-api-key

Endpoints

POST /v1/geocode/forward

Converts a human-readable address into latitude/longitude coordinates and structured components.

POST /v1/geocode/reverse

Converts latitude/longitude coordinates into a formatted address with structured components.

Request

Forward Geocode

Parameter	Type	Required	Description
address	string	Yes	Street address, city, state, and/or postal code
country	string	No	Two-letter country code to scope results (e.g. US, CA)

Reverse Geocode

Parameter	Type	Required	Description
latitude	number	Yes	Latitude coordinate (e.g. 35.1395)
longitude	number	Yes	Longitude coordinate (e.g. -90.0518)

Example Request Body (Forward)

{
  "address": "191 Beale St, Memphis, TN 38103"
}

Example Request Body (Reverse)

{
  "latitude": 35.1395,
  "longitude": -90.0518
}

Response

A successful geocode returns a 200 status with a results array.

Field	Type	Description
results	array	Array of geocode result objects
results[].address_components	object	Structured address: number, street, city, state, postal_code, etc.
results[].address_lines	array	Formatted address lines for display
results[].formatted_address	string	Single-line formatted address
results[].location	object	Coordinates: latitude (number), longitude (number)
results[].properties	object	Additional metadata: gid, fullname, zip range

Example Response (200 OK)

{
  "results": [
    {
      "address_components": {
        "number": "191",
        "street": "Beale",
        "suffix": "St",
        "formatted_street": "Beale St",
        "city": "Memphis",
        "state_province": "TN",
        "postal_code": "38103"
      },
      "formatted_address": "191 Beale St, Memphis, TN 38103",
      "location": {
        "latitude": 35.139537,
        "longitude": -90.051832
      }
    }
  ]
}

Error Codes

Status	Code	Message	Description
400	MISSING_PARAM	Missing required parameter	Required field (address or latitude/longitude) is missing
400	INVALID_COORDS	Invalid latitude or longitude values	Coordinates must be valid numeric values within range
404	NOT_FOUND	Address or coordinates not found	No results could be matched to the input
401	UNAUTHORIZED	Invalid or missing API key	The X-RapidAPI-Key header is missing or invalid
429	RATE_LIMIT	Rate limit exceeded	Request limit for your plan has been reached
500	INTERNAL_ERROR	Internal server error	An unexpected error occurred. Please try again.

Code Examples

cURL (Forward)

              
curl --request POST \

  --url https://frapi-geocode-v1.p.rapidapi.com/v1/geocode/forward \

  --header 'X-RapidAPI-Key: your-api-key' \

  --header 'Content-Type: application/json' \

  --data '{"address": "191 Beale St, Memphis, TN 38103"}'

Python (Reverse)

              
import requests

url = "https://frapi-geocode-v1.p.rapidapi.com/v1/geocode/reverse"
headers = {
    "X-RapidAPI-Key": "your-api-key",
    "Content-Type": "application/json"
}
data = { "latitude": 35.1395, "longitude": -90.0518 }

response = requests.post(url, json=data, headers=headers)
print(response.json())
              
            

JavaScript (Forward)

              
const url = 'https://frapi-geocode-v1.p.rapidapi.com/v1/geocode/forward';
const options = {
  method: 'POST',
  headers: {
    'X-RapidAPI-Key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ address: '191 Beale St, Memphis, TN 38103' })
};

const response = await fetch(url, options);
const data = await response.json();
console.log(data);
              
            

Rate Limits

Request limits depend on your subscription tier. Exceeding your limit returns a 429 status.

Tier	Requests / Month	Rate Limit
Starter (Free)	500	10 req/min
Pro	10,000	60 req/min
Enterprise	100,000	300 req/min

Try It Out

Test the API right in your browser. No API key required.