Forward geocode an address
Signed in? Open this endpoint in the dashboard playground, which uses your organization automatically. Signed out, use Try in Playground below with your API key.
Forward geocoding: turn an address or place name into coordinates and a structured address, for the United States and Canada.
Use one input mode: text for a free-form address, or one or more structured address parameters (name, housenumber, street, postcode, city, state, country). Combining text with structured parameters returns 400; sending neither returns 400.
Served by the Geocoding Waterfall (ADR 0002): libpostal parse, exact Address Point match, Nominatim (OSM and TIGER), interpolation between neighbouring Address Points, then Photon. The best-scoring candidate wins and 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).
Each result carries a per-result datasource: OSM-derived results carry "© OpenStreetMap contributors"; Address Point results carry their sources (for example nad+overture) and each licence's attribution. place_id uses the typed gp:<kind>:<key> format (gp:addr:* for Address Points, gp:osm:* for OSM objects).
Example: GET /geocode/search?text=1600%20Pennsylvania%20Ave%20NW%2C%20Washington%2C%20DC%2020500&apiKey=YOUR_API_KEY
Deviation (unsupported): coverage is the United States and Canada only. Queries for other countries, or filter/countrycodes limited to them, return an empty result set (HTTP 200, no results), not an error.
Deviation (empty): timezone, plus_code, plus_code_short, category, categories, iso3166_2, district, suburb and rank.popularity are never returned.
Deviation (extra): datasource.sources[] (when several Address Point sources agree) and the X-Geo-Stage response header are additions.
Deviation (approximated): rank comes from our own scoring, not Geoapify's; values are on the same scale but not identical. lang, type, filter, bias and limit behave as described on each parameter.
apiKey<token>Your API key from the dashboard, sent as ?apiKey=<key>.
text?stringFree-form address query. Alternative to the structured address parameters; do not combine them. Parsed by libpostal.
1 <= length <= 1024name?stringPlace or amenity name. Structured address input; do not combine with text.
1 <= length <= 1024housenumber?stringHouse number. Structured address input; do not combine with text.
1 <= length <= 1024street?stringStreet name. Structured address input; do not combine with text.
1 <= length <= 1024postcode?stringPostcode or ZIP code. Structured address input; do not combine with text.
1 <= length <= 1024city?stringCity name. Structured address input; do not combine with text.
1 <= length <= 1024state?stringState, province or territory name or code. Structured address input; do not combine with text.
1 <= length <= 1024country?stringCountry name. Structured address input; do not combine with text.
1 <= length <= 1024type?stringRequested location type. Only results of this type are returned. country, state, city and locality are also passed to Nominatim as a feature type.
Deviation (approximated): When type is set the Address Point (canonical and interpolation) stages are skipped, so street and postcode queries are answered from OSM data only. locality matches suburb, district and unknown results.
"country""state""city""postcode""street""amenity""locality"lang?stringResult language (ISO 639-1, case-insensitive).
Deviation (approximated): Only Nominatim (accept-language) and, for en/de/fr/it, Photon honour the language. Address Point results keep the source spelling.
"en""ab""aa""af""ak""sq""am""ar""an""hy""as""av""ae""ay""az""bm""ba""eu""be""bn""bh""bi""bs""br""bg""my""ca""ch""ce""ny""zh""cv""kw""co""cr""hr""cs""da""dv""nl""en""eo""et""ee""fo""fj""fi""fr""ff""gl""ka""de""el""gn""gu""ht""ha""he""hz""hi""ho""hu""ia""id""ie""ga""ig""ik""io""is""it""iu""ja""jv""kl""kn""kr""ks""kk""km""ki""rw""ky""kv""kg""ko""ku""kj""la""lb""lg""li""ln""lo""lt""lu""lv""gv""mk""mg""ms""ml""mt""mi""mr""mh""mn""na""nv""nb""nd""ne""ng""nn""no""ii""nr""oc""oj""cu""om""or""os""pa""pi""fa""pl""ps""pt""qu""rm""rn""ro""ru""sa""sc""sd""se""sm""sg""sr""gd""sn""si""sk""sl""so""st""es""su""sw""ss""sv""ta""te""tg""th""ti""bo""tk""tl""tn""to""tr""ts""tt""tw""ty""ug""uk""ur""uz""ve""vi""vo""wa""cy""wo""fy""xh""yi""yo""za"limit?integerMaximum number of results.
Deviation (approximated): Geoapify documents no default; this service returns 5 results when limit is omitted.
1 <= value <= 1005countrycodes?array<>ISO 3166-1 alpha-2 country filter, comma-separated or repeated (up to 10). Defaults to us,ca when omitted.
Deviation (unsupported): Only the United States and Canada are indexed. Any other country code is accepted but returns an empty result set.
items <= 10filter?array<>Hard result filter. Repeat the parameter or separate items with |. Items: rect:lon1,lat1,lon2,lat2, circle:lon,lat,radiusMeters, countrycode:us,ca (or none/auto for no filter) and place:<gp:osm place id> (bounding box of that OSM object).
Deviation (approximated): circle is pushed down as its bounding box and then applied exactly after the search. place: accepts only gp:osm:<n|w|r><id> Place IDs and filters by that object's bounding box, not its exact boundary; other Place ID kinds return 400. Filters outside the US and Canada return an empty result set.
bias?array<>Soft ranking bias. Repeat the parameter or separate items with |. Items: proximity:lon,lat, rect:lon1,lat1,lon2,lat2, circle:lon,lat,radiusMeters, countrycode:us,ca.
Deviation (approximated): Bias adds up to 0.1 per matching item to the sort order only; rank.confidence is never changed. proximity adds 0.1 / (1 + distance_km / 25). circle also seeds the proximity point sent to Photon.
format?stringResponse serialization: geojson (served as application/geo+json), json or xml.
"geojson""json""geojson""xml"Geocoding results. Format depends on format; the default is GeoJSON. Empty features/results when nothing matches.
- response
GeoJSON FeatureCollection (format=geojson, the default; served as application/geo+json).
type*unknownfeatures*array<>query?Echo of the request input plus the parsed address.
curl -X GET 'https://api.data.graphitelab.ai/v1/geocode/search?text=1600+Pennsylvania+Ave+NW%2C+Washington%2C+DC+20500&name=Lincoln+Memorial&housenumber=1600&street=Pennsylvania+Avenue+NW&postcode=20500&city=Washington&state=DC&country=United+States&type=city&lang=en&limit=5&countrycodes=us&countrycodes=ca&filter=circle%3A-77.0365%2C38.8977%2C5000&filter=countrycode%3Aus&bias=proximity%3A-77.0365%2C38.8977&format=json'{ "results": [ { "name": "Prime Minister's Residence", "country": "Canada", "country_code": "ca", "state": "Ontario", "state_code": "ON", "county": "Eastern Ontario", "city": "Ottawa", "postcode": "K1M 2B2", "street": "Sussex Drive", "housenumber": "24", "lon": -75.6937963, "lat": 45.4441429, "formatted": "24 Sussex Drive, Ottawa, ON K1M 2B2, Canada", "address_line1": "24 Sussex Drive", "address_line2": "Ottawa, ON K1M 2B2, Canada", "result_type": "building", "datasource": { "sourcename": "openstreetmap", "attribution": "© OpenStreetMap contributors", "license": "Open Database License", "url": "https://www.openstreetmap.org/copyright" }, "rank": { "confidence": 1, "confidence_city_level": 1, "confidence_street_level": 1, "confidence_building_level": 1, "match_type": "full_match" }, "place_id": "gp:osm:w230454276", "bbox": { "lon1": -75.694683, "lat1": 45.4435841, "lon2": -75.6926233, "lat2": 45.4448567 } }, { "name": "24 Sussex Drive", "country": "Canada", "country_code": "ca", "state": "Ontario", "state_code": "ON", "city": "Ottawa", "postcode": "K1M 2B2", "street": "Sussex Drive", "lon": -75.6938552, "lat": 45.444413, "formatted": "Sussex Drive, Ottawa, ON K1M 2B2, Canada", "address_line1": "Sussex Drive", "address_line2": "Ottawa, ON K1M 2B2, Canada", "result_type": "unknown", "datasource": { "sourcename": "openstreetmap", "attribution": "© OpenStreetMap contributors", "license": "Open Database License", "url": "https://www.openstreetmap.org/copyright" }, "rank": { "confidence": 0.5, "confidence_city_level": 1, "confidence_street_level": 1, "confidence_building_level": 0, "match_type": "match_by_street", "importance": 0.00000999999999995449 }, "place_id": "gp:osm:w39675229", "bbox": { "lon1": -75.694034, "lat1": 45.444253, "lon2": -75.693684, "lat2": 45.444571 } } ], "query": { "text": "24 Sussex Drive, Ottawa, ON", "parsed": { "housenumber": "24", "street": "sussex drive", "city": "ottawa", "state": "on", "expected_type": "building" } }}