PlaceField

API reference

PlaceField API reference

Technical details for querying cities, administrative areas, regions, and countries worldwide. For a product overview, start with the location autocomplete API page.

Choosing an integration?

Choose one integration path. You do not need to install all three. Use the API for backend or custom frontend control, Basic JS for your own UI, or Full Widget for a ready-made location autocomplete field. Runnable Node/Express, ASP.NET, API Fetch, and widget examples are available in the PlaceField examples repo.

Compare integration options

Scope

This API reference covers location autocomplete for administrative places, including the narrow place geocoding case where a product or form needs city, region, country, and coordinates. PlaceField is not an address autocomplete API, reverse geocoding API, routing API, POI search API, or maps API.

Need the marketing overview instead? Read about the location autocomplete API, city-level form use case, city geocoding use case, or Google Places autocomplete alternative.

Versioning

The public API uses major versions in the URL path. The current public contract is v1. Compatible additions can ship inside v1, while breaking contract changes require a new path such as /v2.

Dataset updates are tracked separately through meta.datasetVersion. Every /v1 response also includes X-PlaceField-Api-Version: v1; future retirements will use standard Deprecation and Sunset headers before an older major version is removed.

Server key usage

GET https://api.placefield.dev/v1/locations/autocomplete?q=paris&geoBias=none&typePreset=default&limit=10
Authorization: Bearer pf_live_xxx

Browser key usage

Demo URL expires and is rate-limited. Use your own API key in production.

Ready

Response 
{
  "status": "Run the request, then expand this response."
}

Keys and browser origins

Public browser keys are sent as query parameters and only work when the request Origin exactly matches an origin in Dashboard. Secret server keys use bearer auth and should stay on your backend. CORS/domain allowlists protect browser reads; they are not a substitute for API keys.

Demo requests copied from this page may include a demo parameter. It is a short-lived, rate-limited token for trying the API from a browser address bar, not a production integration parameter.

Parameters

Name Required Notes
q Yes Search query, 1-120 characters.
country No ISO country code or country name for biasing/filtering.
countries No Comma-separated ISO country-code allowlist.
countryMode No Applies to country. Use bias for softer ranking, or filter when results must stay inside one supplied country. Use countries for a multi-country allowlist.
geoBias No Use country by default to prefer the requester’s country, nearby to prefer closer places, or none for worldwide ranking.
typePreset No default returns normal form-friendly city, municipality, state, province, and country results. broad adds smaller locality/supporting layers such as town, parish, island, and region. admin returns administrative areas and countries only.
types No Advanced comma-separated place types. Overrides typePreset when supplied.
lang No Response language preference. Supports en, pt, es, and fr. Default is en.
limit No 1-20 results. Default is 10.

Response shape

{
  "results": [
    {
      "id": "fr:city:paris",
      "type": "city",
      "name": "Paris",
      "label": "Paris, Ile-de-France, France",
      "country": {
        "code": "FR",
        "name": "France"
      },
      "hierarchy": [
        {
          "type": "country",
          "id": "country:fr",
          "name": "France",
          "code": "FR"
        },
        {
          "type": "region",
          "name": "Ile-de-France",
          "code": "11"
        }
      ],
      "coordinates": {
        "lat": 48.85341,
        "lon": 2.3488
      }
    }
  ],
  "meta": {
    "query": "paris",
    "limit": 10,
    "country": null,
    "countries": null,
    "countryMode": "bias",
    "geoBias": "none",
    "typePreset": "default",
    "types": "city,municipality,state,province,country",
    "language": "en",
    "appliedBiasCountry": null,
    "biasSource": null,
    "geographicBias": {
      "mode": "none",
      "source": null,
      "country": null,
      "coordinatesAvailable": false
    },
    "requestId": "req_...",
    "datasetVersion": "2026.05.01"
  }
}

Dataset attribution

PlaceField maintains central source attribution for hosted datasets at /attributions. Standard API and widget integrations do not need visible attribution beside every field unless a separate data export or redistribution agreement says otherwise.

Related guides

Still deciding what kind of location field to build? Read the location autocomplete decision guide, compare city vs address autocomplete, or learn how to collect location without street addresses.