Locations

Autocomplete location search

getapi.modelmatch.com/v1/locations/suggest

Autocomplete location search. Cities and counties come from Model Match's own location dictionary and carry an id (e.g. city_mo_saint-louis) that city / county filters accept — including for places our data spells differently than a mapping provider does. Street addresses come from Mapbox. Use the mapbox_id from any suggestion with retrieveLocation to get normalized geographic details and coordinates.

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Query parameters

qstringrequired

Search text

limitintegerdefault: 5

Max results (1-10, default 5)

Responses

200objectLocation suggestions

Show attributes

suggestionsobject[]required

Show child attributes

feature_typestringrequired

full_addressstring

idstring

Location dictionary id (e.g. city_mo_saint-louis). Pass this to a city / county filter. Absent on Mapbox address suggestions.

mapbox_idstringrequired

Pass to retrieveLocation. On a dictionary suggestion this is the location id; on a Mapbox suggestion it is the Mapbox feature id.

namestringrequired

place_formattedstring

sourceenum

Where the suggestion came from. dictionary suggestions carry an id that filters accept; mapbox suggestions are addresses and coordinates only.

Options:dictionarymapbox

statestring

totalCountnumber

Records across all entities at this location — a popularity signal for ranking, not a filter result count.

typestring

Location type — city or county.

400objectValidation error

401objectUnauthorized

403objectForbidden (authenticated, but missing required context — e.g. no active organization)

404objectNot found

413objectResponse payload too large — detail endpoint capped to fit Lambda response limits

503objectSearch timed out or the cluster is overloaded — retry after `Retry-After` seconds.

curl -X GET "https://api.modelmatch.com/v1/locations/suggest?q=%3Cstring%3E" \
  -H "x-api-key: $MODEL_MATCH_API_KEY"

import { createClient } from "@model-match/api";

const client = createClient({ apiKey: process.env.MODEL_MATCH_API_KEY });

const { data, error } = await client.locations.suggest({
  query: {
    q: "<q>"
  }
});

import os
import requests

res = requests.get(
    "https://api.modelmatch.com/v1/locations/suggest?q=%3Cstring%3E",
    headers={"x-api-key": os.environ["MODEL_MATCH_API_KEY"]},
)
data = res.json()

200 response

{
  "suggestions": [
    {
      "feature_type": "<string>",
      "full_address": "<string>",
      "id": "<string>",
      "mapbox_id": "<string>",
      "name": "<string>",
      "place_formatted": "<string>",
      "source": "dictionary",
      "state": "<string>",
      "totalCount": 123.45,
      "type": "<string>"
    }
  ]
}