PlaceField Examples

Production-friendly starting points for adding PlaceField location autocomplete to apps, backends, and forms.

PlaceField is a commercial API and hosted JavaScript widget for city, administrative area, and country search. PlaceField itself is not open source; this repository contains sample integration code only.

PlaceField is not an address autocomplete, address validation, reverse geocoding, routing, map tile, or POI search product.

Start Here

Most production apps should put PlaceField behind their own backend route:

Browser or mobile app -> your backend route -> PlaceField API

That keeps a pf_live_... server key on your server and lets your app return only the structured location data it needs.

• Backend/API examples: examples/node-express and examples/aspnet-minimal-api
• Browser widget examples: examples/basic-js, examples/full-widget, and examples/react-widget
• Custom rendering example: examples/api-fetch
• Static examples companion: placefield.github.io/placefield-examples
• Canonical docs: placefield.dev/docs and placefield.dev/api

The GitHub Pages companion is intentionally static. It does not embed a live PlaceField key and does not call the PlaceField API from GitHub Pages.

Choose An Example

Example	Best Starting Point For	Key Setup
examples/node-express	Node/Express backend API route	Replace pf_live_xxx in placefield.config.json
examples/aspnet-minimal-api	ASP.NET Minimal API backend route	Replace pf_live_xxx in appsettings.json
examples/api-fetch	Direct API call with your own rendering	Replace pf_pub_xxx in the page
examples/basic-js	Autocomplete behavior attached to your own input	Replace pf_pub_xxx in the page
examples/full-widget	Ready-made autocomplete field with bundled UI	Replace pf_pub_xxx in the page
examples/react-widget	React/Vite TypeScript app using @placefield/widget and the Full Widget	Replace PLACEFIELD_KEY in src/App.tsx

You do not need to install or copy every example. Pick the closest starting point and adapt that one.

Keys And Origins

These examples use placeholder keys only.

• pf_live_... keys are secret server keys. Keep them on your backend.
• pf_pub_... keys are public browser keys. They can be used from browser examples after you allowlist the exact local or production origin in the PlaceField dashboard.
• Do not commit real API keys.
• Do not add a PlaceField key to GitHub Pages. The Pages site is for discovery and example routing only.

For parameter details, response fields, limits, and product behavior, use the official documentation:

• Docs
• API reference
• Location autocomplete API overview
• Widget overview
• FAQ

Run Locally

Node/Express

cd examples/node-express
npm install
npm run dev

Open:

http://localhost:3000/

ASP.NET Minimal API

cd examples/aspnet-minimal-api
dotnet run

Open:

http://localhost:5187/

Visual Studio users can open examples/aspnet-minimal-api/PlaceField.AspNetMinimalApiExample.sln and press Start Debugging.

Static Browser Examples

npx http-server . -p 8080

Open:

• http://localhost:8080/
• http://localhost:8080/examples/api-fetch/
• http://localhost:8080/examples/basic-js/
• http://localhost:8080/examples/full-widget/
• http://localhost:8080/examples/react-widget/

The React example is a Vite TypeScript app. From examples/react-widget, run npm install, npm run typecheck, and npm run dev to see the live React version.

Maintainer Boundary

Keep this README and the GitHub Pages companion focused on discovery, example selection, and local run instructions. Canonical API contracts, billing, limits, dashboard behavior, and product documentation should stay on placefield.dev.

License

The sample code in this repository is MIT licensed. PlaceField API and hosted widget usage require a PlaceField key and are governed by PlaceField commercial terms.