Documentation

Every request must carry your API credentials, a username and a password, sent with HTTP Basic authentication over HTTPS. We issue credentials when we set up your account; to request them, email contact@geoclarity.net.

By default, credentials only work from the IP addresses you have registered with us. Send us the addresses of your servers when you ask for credentials, or ask us to lift the restriction.

Call the API from your server, not from a browser or a mobile app, so that your credentials stay secret.

Send a GET request with a latitude and a longitude, replacing USERNAME and PASSWORD with your credentials:

curl -u "USERNAME:PASSWORD" \
  "https://api.geoclarity.net/api/v1/address?lat=40.7128&lon=-74.0060"

const credentials = Buffer.from("USERNAME:PASSWORD").toString("base64");

const response = await fetch(
  "https://api.geoclarity.net/api/v1/address?lat=40.7128&lon=-74.0060",
  { headers: { Authorization: `Basic ${credentials}` } },
);
const data = await response.json();

console.log(data.results[0].formatted);
// New York City Hall, 260 Broadway, New York, NY 10000, United States of America

import requests

response = requests.get(
    "https://api.geoclarity.net/api/v1/address",
    params={"lat": 40.7128, "lon": -74.0060},
    auth=("USERNAME", "PASSWORD"),
)
data = response.json()

print(data["results"][0]["formatted"])
# New York City Hall, 260 Broadway, New York, NY 10000, United States of America

The response is JSON. For the coordinate above it looks like this:

{
  "results": [
    {
      "bounds": {
        "northeast": { "lat": 40.7130254, "lng": -74.0055687 },
        "southwest": { "lat": 40.712445, "lng": -74.0064455 }
      },
      "components": {
        "continent": "North America",
        "country": "United States of America",
        "city": "New York",
        "amenity": "New York City Hall",
        "county": "New York County",
        "postcode": "10000",
        "_type": "amenity",
        "house_number": "260",
        "ISO_3166-1_alpha-2": "US",
        "ISO_3166-1_alpha-3": "USA",
        "country_code": "us",
        "road": "Broadway",
        "neighbourhood": "Tribeca",
        "suburb": "Manhattan",
        "_category": "amenity",
        "state": "New York",
        "ISO_3166-2": ["US-NY"],
        "state_code": "NY",
        "quarter": "Lower Manhattan"
      },
      "confidence": 9,
      "distance_from_q": { "meters": 8 },
      "formatted": "New York City Hall, 260 Broadway, New York, NY 10000, United States of America",
      "geometry": { "lat": 40.7127395, "lng": -74.005939 }
    }
  ],
  "total_results": 1
}

GET https://api.geoclarity.net/api/v1/address

Coordinates use WGS 84, the system used by GPS. Send both parameters as decimal numbers with a period as the decimal separator.

Coverage

The API covers the United States.

The matched place is returned in results, and total_results is the number of results. Each result has these fields:

When nothing is found

If there is no address for the coordinate, such as a point in open ocean, the request still succeeds and the result list is empty:

{
  "results": [],
  "total_results": 0
}

Confidence

confidence tells you what kind of place the coordinate was matched to. Higher is more precise.

Address components

Which components are present depends on the place: a coordinate on a rural road may have no house_number, for example. Treat every component as optional.

The HTTP status code tells you what happened:

Responses with status 400, 500 and 502 carry a JSON body with a single error message:

{
  "error": "Geocoding service unavailable"
}

Results are derived from OpenStreetMap data. If you use the API in a publicly available product, credit OpenStreetMap, for example with “© OpenStreetMap contributors” linked to openstreetmap.org/copyright.

You may store the results and keep them for as long as you like, including after you stop using the API. The details are in our Terms and Conditions.

The first 100,000 requests each month are free. Beyond that, usage is billed per 1,000 requests, starting at $0.04 and falling to $0.01 at high volume. See pricing for the full table and a cost estimator.

Questions about integrating the API, or something not covered here? Email contact@geoclarity.net.