Integration options

PlaceField integration docs

Copy the API, Basic JS, or Full Widget setup for a structured location integration. For a product overview, start with the location autocomplete widget page, or browse the public examples on GitHub.

API

Use this if you want full control over place autocomplete from your backend, frontend, or data workflow.

Read API reference

Basic JS

Use this if you want PlaceField results attached to your own input and UI.

Copy Basic JS

Full Widget

Use this if you want a polished location autocomplete widget with minimal customization.

Copy Full Widget

Prefer runnable examples?

The public examples repository includes backend-first Node/Express and ASP.NET Minimal API starters, plus API Fetch, Basic JS, Full Widget, and React TypeScript examples for browser integrations.

View GitHub examples

npm package for bundler apps

Install @placefield/widget when a React, Vite, or other bundler-based app wants TypeScript types and loader helpers. The package still loads the supported hosted PlaceField assets, so CDN and npm integrations use the same browser widget surface.

1. Install

npm install @placefield/widget

2. Create the widget

import {
  createPlaceFieldWidget,
  type PlaceFieldAutocompleteResult,
  type PlaceFieldWidgetOptions
} from "@placefield/widget";

const options: PlaceFieldWidgetOptions = {
  key: "pf_pub_xxx",
  geoBias: "country",
  typePreset: "default",
  lang: "en",
  mobile: "fullscreen",
  onSelect(result: PlaceFieldAutocompleteResult) {
    console.log(result.id, result.label);
  }
};

const widget = await createPlaceFieldWidget("#city", options);

What the browser options look like

These examples show the visual difference between the lightweight Basic JS path and the more complete Full Widget path.

Basic JS

Autocomplete behavior attached to an input you style yourself.

Full Widget

Bundled field styling, clear button, and richer result rows.

Fullscreen mobile search

Optional focused mobile mode for forms where completion quality matters.

Animated fullscreen mobile PlaceField search flow opening from a location input and showing matching location results.

What these docs cover

These docs cover integration mechanics. PlaceField returns city, administrative area, region, and country suggestions for apps, backends, and forms, including coordinates for place-level geocoding use cases; it does not provide address autocomplete, route planning, reverse geocoding, map tiles, or POI search.

For search-focused overviews, see location autocomplete API, location autocomplete widget, city-level forms, and city geocoding.

Basic JS

The Basic JS bundle stays small and dependency-free. It attaches autocomplete behavior to an existing input while leaving the surrounding UI to you.

1. Add the assets

<link rel="stylesheet" href="https://cdn.placefield.dev/placefield.css">
<script src="https://cdn.placefield.dev/placefield.min.js"></script>

2. Prepare your fields

<input id="city" name="city" autocomplete="off">
<input id="location_id" name="location_id" type="hidden">
<input id="country" name="country" type="hidden">
<input id="hierarchy" name="hierarchy" type="hidden">
<input id="lat" name="lat" type="hidden">
<input id="lon" name="lon" type="hidden">

3. Attach PlaceField

PlaceField.attach("#city", {
  endpoint: "https://api.placefield.dev/v1/locations/autocomplete",
  key: "pf_pub_xxx",
  geoBias: "country",
  typePreset: "default",
  lang: "en",
  fields: {
    id: "#location_id",
    country: "#country",
    hierarchy: "#hierarchy",
    lat: "#lat",
    lon: "#lon"
  }
});

Full Widget

The Full Widget includes a ready-made location autocomplete UI and CSS. It uses a normal dropdown by default on desktop and mobile, and can enable fullscreen mobile search with one option.

1. Add the assets

<link rel="stylesheet" href="https://cdn.placefield.dev/placefield-widget.css">
<script src="https://cdn.placefield.dev/placefield-widget.min.js"></script>

2. Prepare your fields

<input id="city" name="city" autocomplete="off">
<input id="location_id" name="location_id" type="hidden">
<input id="country" name="country" type="hidden">
<input id="hierarchy" name="hierarchy" type="hidden">
<input id="lat" name="lat" type="hidden">
<input id="lon" name="lon" type="hidden">

3. Start the widget

PlaceField.widget("#city", {
  endpoint: "https://api.placefield.dev/v1/locations/autocomplete",
  key: "pf_pub_xxx",
  geoBias: "country",
  typePreset: "default",
  lang: "en",
  fields: {
    id: "#location_id",
    country: "#country",
    hierarchy: "#hierarchy",
    lat: "#lat",
    lon: "#lon"
  }
});

Optional fullscreen mobile search

For mobile-heavy forms, the Full Widget can switch to a focused fullscreen search experience without custom mobile UI work.

Enable mobile fullscreen

PlaceField.widget("#city", {
  endpoint: "https://api.placefield.dev/v1/locations/autocomplete",
  key: "pf_pub_xxx",
  mobile: "fullscreen"
});

Keys, origins, and shared options

Browser integrations use public keys and require the exact production site origin in Dashboard. Omit country to prefer the requester’s country, pass geoBias: "nearby" to prefer closer places, pass geoBias: "none" for worldwide ranking, and use lang to request en, pt, es, or fr display names.

PlaceField maintains central dataset attribution at /attributions. Normal widget integrations do not need attribution text beside each field.

Related guides

Not sure whether your form needs country, region, city, address, POI search, geocoding, or reverse geocoding? Read the location autocomplete decision guide, compare city vs address autocomplete, or inspect the public PlaceField examples.