Forward geocoding

GET /v1/geocode/search converts a free-form address (or structured address fields) into coordinates plus a normalized, structured address. Use it when you have text from a user or a database and need a point on the map, a clean formatted address, or a stable place_id. It is the Geoapify-compatible forward geocoder (operationId: forwardGeocode).

How it worksCopy Anchor Link

The request runs through the Geocoding Waterfall (ADR 0002), which is hand-rolled in the gateway:

1. libpostal parses text into house number, street, city, state and postcode. Structured parameters skip parsing.

2. Canonical Address exact match in the Address Point layer (Overture and NAR, with NAD filling gaps; stored in the same Postgres/PostGIS cluster as Nominatim).

3. Nominatim (OSM plus Census TIGER), structured query first, then free text.

4. Interpolation between neighbouring Address Points.

5. Photon (OSM-based search index) as the last resort.

A stage's answer is accepted when its best candidate scores at least 0.8. Otherwise the next stage runs and the best candidate overall wins. The scoring fills the rank fields. The X-Geo-Stage response header names the stage that produced the first result: canonical, nominatim, interpolation, photon or none.

Quick startCopy Anchor Link

curl -s \
  "https://api.data.graphitelab.ai/v1/geocode/search?text=1600%20Pennsylvania%20Ave%20NW,%20Washington,%20DC%2020500&apiKey=$GRAPHITE_API_KEY"

The default format is GeoJSON. This query is answered by an exact Address Point match (response trimmed):

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "country_code": "us",
        "state_code": "DC",
        "city": "Washington",
        "postcode": "20500",
        "street": "PENNSYLVANIA Avenue Northwest",
        "housenumber": "1600",
        "lon": -77.03654697024702,
        "lat": 38.89767510742324,
        "formatted": "1600 PENNSYLVANIA Avenue Northwest, Washington, DC 20500, United States",
        "result_type": "building",
        "datasource": {
          "sourcename": "nad+overture",
          "attribution": "National Address Database, U.S. Department of Transportation; © Overture Maps Foundation and its address sources"
        },
        "rank": { "confidence": 1, "match_type": "full_match", "importance": 1 },
        "place_id": "gp:addr:canonical:37388970"
      },
      "geometry": { "type": "Point", "coordinates": [-77.03654697024702, 38.89767510742324] }
    }
  ],
  "query": {
    "text": "1600 Pennsylvania Ave NW, Washington, DC 20500",
    "parsed": { "housenumber": "1600", "street": "pennsylvania ave nw", "city": "washington", "state": "dc", "postcode": "20500", "expected_type": "building" }
  }
}

ParametersCopy Anchor Link

Use one input mode: text, or the structured fields. Combining them returns 400, and sending neither returns 400.

Full parameter reference

ResponseCopy Anchor Link

Each GeoJSON feature (or entry in results for json and xml) carries:

• lon, lat, and a geometry Point in GeoJSON.

• formatted, address_line1, address_line2 and the structured parts (housenumber, street, city, state_code, postcode, country_code).

• result_type: for example building, street, city, unknown.

• place_id: typed gp:<kind>:<key>. gp:addr:* is an Address Point, gp:osm:* is an OSM object (for example gp:osm:w230454276, a way). OSM Place IDs can be used in filter=place:.

• datasource: the source this result came from. OSM-derived results carry "© OpenStreetMap contributors" and the ODbL. Address Point results carry their sources (for example nad+overture) with each licence's attribution; when several sources agree they are listed in datasource.sources[].

• rank: confidence (0 to 1) with city, street and building level variants, match_type (for example full_match, match_by_street, match_by_city_or_disrict) and importance where present.

• bbox: present on OSM results that have an extent.

• query.parsed: how the input was parsed, including expected_type.

Differences from GeoapifyCopy Anchor Link

• unsupported: US and Canada only. Other countries return an empty result set with HTTP 200, not an error.

• empty: timezone, plus_code, plus_code_short, category, categories, iso3166_2, district, suburb and rank.popularity are never returned.

• extra: datasource.sources[] and the X-Geo-Stage response header are additions.

• approximated: rank comes from our own scoring: same scale, not identical values. lang, type, filter, bias and limit are approximated:

  • type skips the Address Point stages; locality matches suburb, district and unknown results.

  • lang is honored only by Nominatim and (en/de/fr/it) Photon; Address Point results keep the source spelling.

  • limit defaults to 5 (Geoapify documents no default).

  • filter: circle is pushed down as its bounding box, then applied exactly. place: accepts only gp:osm:<n|w|r><id> and filters by that object's bounding box, not its exact boundary; other Place ID kinds return 400.

  • bias adds up to 0.1 per matching item to the sort order only and never changes rank.confidence. proximity adds 0.1 / (1 + distance_km / 25).

US and Canada notesCopy Anchor Link

• US addresses come from Overture, NAD and OSM/TIGER. Canadian addresses come from Overture, NAR (StatCan National Address Register) and OSM.

• Canadian postcodes in a query are anchored by the full code or its 3-character FSA prefix (for example K1M).

• Province and territory names or codes are accepted in state (for example ON, Ontario, Québec).

• Canadian OSM results can carry bilingual names, as in New Brunswick / Nouveau-Brunswick. lang=fr is honored only by Nominatim and Photon.

• Address Point results echo the source's casing, for example PENNSYLVANIA Avenue Northwest.

• countrycodes or filter limited to other countries returns an empty result set.

More examplesCopy Anchor Link

curl -s \
  "https://api.data.graphitelab.ai/v1/geocode/search?text=24%20Sussex%20Drive,%20Ottawa,%20ON&apiKey=$GRAPHITE_API_KEY"

Errors and limitsCopy Anchor Link

limit is capped at 100 (default 5), countrycodes at 10 items, and string inputs at 1024 characters. Over 60 requests per minute returns 429.