Autocomplete

GET /v1/geocode/autocomplete returns ranked suggestions for a partial address or place name. Use it behind a search box while the user is still typing; use forward geocoding once you have a complete address and want the best single match.

How it worksCopy Anchor Link

One Engine answers: Photon, the fuzzy prefix-search engine, imported from our Nominatim database. There is no Geocoding Waterfall here.

1. The gateway sends your text to Photon, asking for up to three times limit candidates (capped at 100). lang (en, de, fr, it only), type (as a Photon layer), bias proximity and the filter bounding box are passed along.
2. Candidates are filtered to the requested countries (default us,ca), then by type, filter and duplicates.
3. Each result gets a rank.confidence: the share of the typed text covered by the result's address line. If you pass bias, results are re-sorted by confidence plus a bias bonus.
4. The list is cut to limit, and each result gets its datasource (see below).

Address Points (house-level addresses from NAD, StatCan NAR and Overture) are injected into the Photon index. Those results have result_type: building and gp:addr:canonical:<id> Place IDs. Everything else comes from OpenStreetMap and has gp:osm:... Place IDs.

Quick startCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/geocode/autocomplete?text=350+5th+ave+new+y&limit=3&apiKey=$GRAPHITE_API_KEY"

Trimmed response (GeoJSON, the default):

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "WSKQ-FM (New York)",
        "country_code": "us",
        "state_code": "NY",
        "city": "New York",
        "postcode": "10118",
        "street": "5th Avenue",
        "housenumber": "350",
        "lon": -73.9856942,
        "lat": 40.7484273,
        "formatted": "350 5th Avenue, New York, NY 10118, United States",
        "result_type": "building",
        "datasource": {
          "sourcename": "openstreetmap",
          "attribution": "© OpenStreetMap contributors",
          "license": "Open Database License"
        },
        "rank": { "confidence": 0.85, "match_type": "full_match" },
        "place_id": "gp:osm:n357606907"
      },
      "geometry": { "type": "Point", "coordinates": [-73.9856942, 40.7484273] }
    }
  ],
  "query": { "text": "350 5th ave new y" }
}

ParametersCopy Anchor Link

Full parameter reference

ResponseCopy Anchor Link

Each result is a GeoJSON Feature (or an entry in results with format=json). The fields that matter most:

rank.importance and rank.popularity are not returned. Fields beyond the response schema (timezone, plus codes, categories) are not returned either.

Differences from GeoapifyCopy Anchor Link

• approximated: rank.confidence* is the share of the typed text covered by the result. importance and popularity are not returned.

• approximated: lang only changes results for en, de, fr and it; other accepted values behave as the default.

• approximated: countrycodes only has data for us and ca; other codes return empty results.

• extra: filter=place:<id> takes a gateway Place ID (gp:osm:<n|w|r><id>, per ADR 0006), not a Geoapify place id, and filters to that OSM object's bounding box.

• unsupported: type=locality is rejected with 400.

US and Canada notesCopy Anchor Link

• Results are limited to the United States and Canada. The default countrycodes is us,ca.

• Canadian results include province names and codes (state, state_code) and full six-character postal codes where the source has them. Use lang=fr for French street and place names, for example "Rue Sainte-Catherine Est" in Montréal.

• House-level suggestions come from Address Points: NAD in the US, StatCan NAR in Canada, plus Overture. Without a matching Address Point, a house number can still come from OpenStreetMap, as in the quick start.

• Address Point casing is echoed from the source, so you may see all-caps street names such as PENNSYLVANIA Avenue Northwest.

More examplesCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/geocode/autocomplete?text=rue+sainte-catherine+montr&lang=fr&limit=3&apiKey=$GRAPHITE_API_KEY"

Errors and limitsCopy Anchor Link

Limits: text up to 1024 characters, limit 1 to 100 (default 5), countrycodes up to 10 values. The gateway waits up to 8 seconds for Photon.