Guide

City vs address autocomplete: which should your form use?

Choose the smallest location field that supports the job your product needs to do. Many forms need a city, region, or country. Some forms truly need a complete street address.

Use city autocomplete when

You need a user's general location for profiles, discovery, regional filtering, communities, CRM records, or marketplace listings.

Use address autocomplete when

You need delivery, billing, tax, identity verification, property lookup, appointment routing, or a precise service location.

Use neither when

You only need a country selector, a fixed set of regions, or an internal location taxonomy that users should not search freely.

The decision rule

If the product outcome depends on a street, building, postal code, or deliverable address, use address autocomplete or address validation. If the outcome depends on where someone is broadly based, city and country autocomplete is usually enough.

PlaceField supports the second case: structured autocomplete for cities, municipalities, administrative areas, regions, and countries. It does not validate postal addresses, route vehicles, search businesses, or return map UI.

For the broader framework across country, region, city, address, POI search, geocoding, and reverse geocoding fields, read the location autocomplete decision guide.

Common examples

These are practical starting points. Your legal, operational, or fraud requirements may still require more precise data.

User profile

City, region, and country are often enough for a public profile or community member directory.

Marketplace listing

A listing may need city-level discovery without exposing a seller's street address.

Checkout or shipping

Use address autocomplete or address validation because the exact destination matters.

Service area search

Start with city or region if broad matching is enough; use address or geocoding only when distance from a precise point matters.

What to store

For city-level forms, avoid storing only the text a user typed. Store a stable location ID, display name, place type, country, hierarchy, and coordinates when available.

That gives your product normalized data for filtering and reporting without collecting a full street address.

City-level result shape

{
  "id": "fr:city:paris",
  "type": "city",
  "name": "Paris",
  "country": { "code": "FR", "name": "France" },
  "hierarchy": [],
  "coordinates": { "lat": 48.85341, "lon": 2.3488 }
}

Where PlaceField fits

Use the PlaceField location autocomplete API or JavaScript widget when your form should suggest cities, regions, administrative areas, and countries. Use a dedicated address product when your workflow needs a validated street address.

Unsure which field your product needs?

Tell us what the form is for and what you need to do with the location after submission.