Examples

Ready-to-use code examples for integrating with the geocodeme.net API in your preferred language.

Before You Start

All examples assume you have:

1. A valid API key (get one here)
2. Set the key in an environment variable:

export GEOCODEME_API_KEY="gm_YOUR_KEY"

Forward Geocoding

Convert an address to coordinates.

cURL

curl -H "X-Api-Key: $GEOCODEME_API_KEY" \
  "https://api.geocodeme.net/v1/geocode?q=1+rue+de+Rivoli+Paris&limit=1"

Python

import os
import requests

API_KEY = os.environ["GEOCODEME_API_KEY"]
BASE_URL = "https://api.geocodeme.net/v1"

response = requests.get(
    f"{BASE_URL}/geocode",
    params={"q": "1 rue de Rivoli, Paris", "limit": 1},
    headers={"X-Api-Key": API_KEY},
)
response.raise_for_status()

data = response.json()
location = data["results"][0]
print(f"{location['display_name']}: {location['lat']}, {location['lon']}")
print(data["attribution"])

JavaScript

const API_KEY = process.env.GEOCODEME_API_KEY;
const BASE_URL = "https://api.geocodeme.net/v1";

const response = await fetch(
  `${BASE_URL}/geocode?q=1+rue+de+Rivoli+Paris&limit=1`,
  { headers: { "X-Api-Key": API_KEY } }
);

if (!response.ok) {
  const error = await response.json();
  console.error(error.error.message);
  process.exit(1);
}

const data = await response.json();
const location = data.results[0];
console.log(`${location.display_name}: ${location.lat}, ${location.lon}`);
console.log(data.attribution);

Reverse Geocoding

Convert coordinates to an address.

cURL

curl -H "X-Api-Key: $GEOCODEME_API_KEY" \
  "https://api.geocodeme.net/v1/reverse?lat=48.8566&lon=2.3522"

Python

response = requests.get(
    f"{BASE_URL}/reverse",
    params={"lat": 48.8566, "lon": 2.3522},
    headers={"X-Api-Key": API_KEY},
)
response.raise_for_status()

data = response.json()
if data["result"] is not None:
    print(data["result"]["display_name"])
print(data["attribution"])

JavaScript

const reverseResponse = await fetch(
  `${BASE_URL}/reverse?lat=48.8566&lon=2.3522`,
  { headers: { "X-Api-Key": API_KEY } }
);

if (!reverseResponse.ok) {
  const error = await reverseResponse.json();
  console.error(error.error.message);
  process.exit(1);
}

const reverseData = await reverseResponse.json();
if (reverseData.result !== null) {
  console.log(reverseData.result.display_name);
}
console.log(reverseData.attribution);

Optional Fields

The address field is optional and may be absent depending on the result. Always check for its presence before accessing it; for example, location.get("address") in Python or location.address?.city in JavaScript. Note that /v1/reverse returns a single result object (or null), while /v1/geocode returns a results array.

Language-Specific Pages

• JavaScript: using fetch in Node.js or the browser
• Python: using the requests library
• PHP: using curl_init() with PHP 7.4+
• cURL: command-line examples for all endpoints