Developer console
// place-search

Performs a batch place search based on RFC 8805 (geofeed).

POSThttps://<tenant>.<api>.fastah.net/geofeeds/place-search

Performs a batch place search based on RFC 8805 (geofeed).

Authorizations

Authorizationstring · headerrequired

Every request needs a Fastah API key sent as a bearer token or as a query parameter. Keys are issued in the Fastah console.

format: Bearer <token>

Body

application/json · required

rowsrfc8805RowPlaceSearchParams[]required

Array of rows for the batch place search.

min items: 1 · max items: 1000
Show child attributes (5)
rowKeystringrequired

Opaque caller-assigned key used to deduplicate and correlate a row. It is unique within a batch and echoed unchanged; it is not required to be a hash.

min length: 32 · max length: 128 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{31,127}$
countryCodestringrequired

RFC 8805 country field. Fastah trims whitespace and matches alpha-2 values case-insensitively. Empty or ZZ means do not geolocate; other semantic invalidity is reported for this row.

max length: 16
regionCodestring

Optional RFC 8805 region field. Fastah trims whitespace, accepts case-insensitive ISO 3166-2-style values, and reports malformed or country-mismatched values for this row.

max length: 16
cityNamestring

Optional RFC 8805 city field. Fastah trims edge whitespace; commas and line breaks are reported as invalid for this row.

max length: 200
searchModerfc8805SearchMode

Fastah place-search preference. Auto returns the best available suggestion; prefer_larger_area favors a region or country when zooming out; prefer_larger_population_center favors a regional or national population center.

Response

200application/json

Ordered per-row place-search results.

resultsrestRfc8805RowPlaceResult[]required

Exactly one result per input row, in input order and correlated by rowKey.

Show child attributes (4)
rowKeystringrequired

Opaque caller-assigned key used to deduplicate and correlate a row. It is unique within a batch and echoed unchanged; it is not required to be a hash.

min length: 32 · max length: 128 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{31,127}$
matchesrestRfc8805Location[]required

Ordered best-first matches. Empty for non-matched or do-not-geolocate rows.

Show child attributes (16)
countryNamestringrequired

Country name as a display string

countryCodestringrequired

ISO 3166-1 alpha-2 country code

flagEmojistringrequired

The flag emoji corresponding to the country code (e.g. 🇺🇸 for US, 🇮🇳 for IN)

sovereignCountryCodestringrequired

ISO 3166-1 alpha-2 code of the sovereign country. Equals countryCode for independent nations. Differs for dependent territories, e.g. 'US' when countryCode is 'UM' (US Minor Outlying Islands), or 'GB' when countryCode is 'IO' (British Indian Ocean Territory).

min length: 2
stateNamestringrequired

Name of the state, province, or top-level administrative subdivision of a country. May be empty for smaller countries without a commonly-used subdivision, or when placeType is 'country'.

stateCodestringrequired

ISO 3166-2 code, if available, of the state, province, or top-level administrative subdivision. May be empty for countries without a commonly-used subdivision code.

placeNamestringrequired

Name of the resolved location, which may be a city, region, or country depending on placeType

placeTypeenumrequired

The geographic granularity of this location result. A 'city' is the most precise, 'region' indicates a state or province, and 'country' means a country or territory.

allowed: city, region, country
longLatnumber · double[]required

Longitude, Latitude representing the approximate geographical center, to be interpreted together with accuracyRadius - the radius in kilometers around this point as a confidence region.

min items: 2 · max items: 2
boundingBoxnumber · double[]required

The rectangular bounding box of the matched place as [minLong, minLat, maxLong, maxLat], providing the geographic extent of the resolved location.

min items: 4 · max items: 4
accuracyRadiusKmintegerrequired

Confidence radius in kilometers around the center point geo-coordinates in longLat

minimum: 10
tzstringrequired

IANA time zone identifier for this location. May be empty for large-area regions or countries that span multiple time zones.

h3Cellsstring[]required

Array of Uber H3 hexagonal cell indices that cover the geographic extent of this matched place, enabling efficient spatial indexing and hierarchical geofencing.

min items: 0
placeIdGeonamesinteger · int64required

A stable place ID - in this case within the Geonames.org place names database

default: 0
continentCodestringrequired

2-letter continent code

min length: 2
populationWeightnumber · floatrequired

GeoNames population divided by country population, as a percentage. Used only as an ordering weight; it is not a confidence score.

minimum: 0 · maximum: 100
isExplicitlyDoNotGeolocatebooleanrequired

True when the row's country is empty or `ZZ`.

messagestringrequired

Human-readable explanation.

400application/json

Batch validation failure.

ipstring

The IP address which is described in this response

messagestringrequired

A description of what went wrong