Address autocomplete is a search-as-you-type interface that suggests addresses, places, and points of interest as a user types, ranked by relevance and proximity. Also called type-ahead search, place search suggestions, or predictive search, address autocomplete is what turns a slow, error-prone address form into a two-tap interaction. The Stadia Maps Autocomplete Search API powers this experience through a fast, partial-input endpoint plus first-party SDKs for the web, iOS, and Android.

Key Takeaways

  • Address autocomplete suggests places as a user types, based on partial input and typically ranked by proximity or a focus point.
  • It is not a substitute for forward geocoding. Autocomplete is tuned for speed on partial input; forward geocoding is tuned for accuracy on complete input and can interpolate addresses.
  • Stadia Maps ships three first-party SDKs (MapLibre GL JS, SwiftUI, Jetpack Compose) that handle debouncing, caching, and result ordering out of the box.
  • The Stadia Maps SDKs default to a 100ms minimum wait period between requests and a 3-character minimum input length.
  • Each autocomplete request is billed as a single request from the unified Stadia Maps API credit pool.

How Address Autocomplete Works

Autocomplete is a variant of forward geocoding tuned for speed on incomplete input. It follows this rough flow:

  1. User types. The client waits for a minimum number of characters (typically two or three) before firing the first request.
  2. Debounce. The client waits a short interval (roughly 100ms) after each keystroke before sending a request, so it does not overwhelm the server on fast typing.
  3. Server searches. The Stadia Maps Autocomplete Search API matches the partial input against the geocoding database and returns ranked candidates.
  4. Client renders results. Suggestions appear under the search field, typically 3 to 5 at a time.
  5. User selects one. The application takes the selected feature (with its full coordinates, address components, and layer) and moves on to the next step.

Two implementation details that matter in production:

  • Out-of-order responses. Fast typing produces overlapping requests. The client must show the response for the most recent input, not the last one to arrive. Modern async frameworks and the Stadia Maps SDKs handle this automatically.
  • Result caching. Recent queries can be served from the local cache, which cuts perceived latency and reduces API calls.

Which Autocomplete SDK Should You Use?

Stadia Maps ships three first-party SDKs for address autocomplete, each purpose-built for its platform. All of them handle debouncing, caching, out-of-order responses, and result ordering by default.

If none of the three fit your stack (React Native, Flutter, a custom UI framework, or a server-side integration), use the underlying HTTP API directly. The Stadia Maps official SDKs also expose the endpoint from TypeScript, Python, Kotlin, Swift, and PHP.

Address Autocomplete Parameters That Matter

The Autocomplete Search endpoint takes one required parameter and several optional ones that tune the result set.

  • text: The partial user input. Required.
  • focus.point.lat / focus.point.lon: Bias results toward a focus point. Typically the map center or the user's known location.
  • boundary.rect.*, boundary.circle.*, boundary.country, boundary.gid: Hard limits on where results can appear. Use these when your product only operates in specific regions.
  • layers: Restrict to specific layers (address, venue, poi, street, locality, and more). Fewer layers means faster, more relevant results. layers=coarse is the fastest option when you do not need addresses or POIs.
  • sources: Restrict to specific data sources (openstreetmap, openaddresses, whosonfirst, geonames, foursquare).
  • size: Maximum number of results to return. Default is 10; most autocomplete UIs display 3 to 5.
  • lang: A BCP47 language tag for localized results.

Autocomplete Defaults Worth Knowing

The Stadia Maps SDKs enforce a set of defaults documented in the API and SDK references. Each one exists to balance API cost, server load, and interaction responsiveness.

  • Minimum input length. The Autocomplete Search docs recommend waiting for two or three characters of user input before sending a query. The MapLibre GL JS Search Box plugin defaults minInputLength to 3.
  • Debouncing. The MapLibre plugin defaults minWaitPeriodMs to 100ms, meaning it waits 100ms between requests as the user types. The docs recommend throttling or debouncing for interactive applications; the ready-to-go integrations handle it automatically.
  • Result caching. The MapLibre plugin caches recent results to avoid duplicate calls.
  • Out-of-order response handling. The docs call this out explicitly: "network requests might arrive out of order... our frameworks handle it automatically." Take care if you build your own low-level integration.
  • Maximum results. The MapLibre plugin defaults maxResults to 5.
  • Layer selection. Specifying only the layers you need improves relevance and performance. layers=coarse is especially useful when POIs and addresses are not needed.

How Do You Add Address Autocomplete?

Here is what a direct call to the Stadia Maps Autocomplete Search API looks like. This example searches for a partial query in Tallinn, Estonia.

GET https://api.stadiamaps.com/geocoding/v2/autocomplete?text=Union+Squa&lang=en

The response is a GeoJSON FeatureCollection. Each feature includes coordinates, parsed address components, layer, confidence score, and source attribution. Full response format details are in the Common Response Format docs.

For most applications, the MapLibre GL JS Search Box plugin, SwiftUI Autocomplete Search, or Jetpack Compose Autocomplete Search will be faster than building a UI on top of the raw API. For runnable code against the HTTP endpoint in TypeScript, Python, Kotlin, Swift, PHP, or cURL, see the Autocomplete Search API docs.

Where Address Autocomplete Falls Short

Autocomplete is not the right tool for every search interaction. Real limits worth knowing:

  • Autocomplete does not interpolate addresses. If a specific house number does not exist in the underlying data, forward geocoding can estimate it from surrounding addresses. Autocomplete cannot. Fall back to forward geocoding once the user finalizes their query.
  • Very short queries are noisy. A one-character query returns hundreds of matches. The Stadia Maps SDKs default to a 3-character minimum. Lowering that produces bad UX.
  • Ranking is context-dependent. Without a focus.point or a boundary, "Springfield" could match any of dozens. Provide a focus point or country hint whenever possible.
  • Layer choice affects results. If you only need addresses and POIs, exclude administrative layers to speed things up. If you only need administrative context, use layers=coarse for the fastest possible search.
  • Two providers rarely agree exactly. Different providers use different data, different scoring, and different ranking logic. Standardize on one provider to keep your product consistent.

Address Autocomplete vs. Forward Geocoding: Which Do You Need?

Both convert human-readable place input into coordinates. They optimize for different phases of the user interaction.

  • Use address autocomplete while the user is still typing. Fast responses, partial input, ranked suggestions.
  • Use forward geocoding once the user finalizes their query (for example, by pressing Enter or submitting a form). Better accuracy on complete input, and forward geocoding can interpolate house numbers that autocomplete cannot.

The MapLibre GL JS Search Box plugin can automatically switch to the forward geocoding endpoint on Enter via the searchOnEnter option, if your plan includes the forward geocoding endpoint. See the Stadia Maps pricing page for plan details.

Common Address Autocomplete Use Cases

Autocomplete appears wherever a product asks a user to enter a real-world place.

  • Checkout and shipping forms. Users select their delivery address from suggestions instead of typing the full string. Fewer errors, faster completion, and higher form conversion.
  • Ride-share and delivery pickup. Rider or customer picks their pickup or drop-off from a search field. Focus point is set to the current GPS location so nearby options rank first.
  • Store locator and site finder. User types a city or zip code and the map centers on the selected result.
  • Map-based search interfaces. Real estate, travel, and outdoor apps let users search for places directly on the map.
  • Data entry and CRM lookup. Sales and support tools use autocomplete to attach a canonical place to a record.
  • Point-of-interest discovery. Restaurants, hotels, landmarks, and businesses surface as venues the user can select without knowing the full name.

Frequently Asked Questions

What is address autocomplete used for?

Address autocomplete is used to suggest places, addresses, and points of interest as a user types. It powers search-as-you-type experiences in checkout flows, store locators, ride-share pickup selection, and any interface where a user needs to find and select a real-world location quickly.

What is the difference between address autocomplete and forward geocoding?

Autocomplete is optimized for speed on partial input. Forward geocoding is optimized for accuracy on complete input and can interpolate addresses. Use autocomplete for interactive search-as-you-type; switch to forward geocoding when the user finalizes the query, for example by pressing Enter.

Which SDKs does Stadia Maps offer for address autocomplete?

Stadia Maps offers three first-party SDKs for address autocomplete: the MapLibre GL JS Search Box plugin for the web, SwiftUI Autocomplete Search for iOS, and Jetpack Compose Autocomplete Search for Android. Each handles debouncing, caching, and result ordering out of the box. If none fit, the underlying HTTP API is available directly.

What are the default autocomplete timing and input settings on Stadia Maps?

The Stadia Maps autocomplete SDKs default to a 100ms minimum wait period between requests (minWaitPeriodMs) and a 3-character minimum input length (minInputLength). The MapLibre GL JS Search Box plugin also defaults maxResults to 5. These defaults balance server load with responsiveness.

How is an address autocomplete request billed on Stadia Maps?

Autocomplete requests are billed from the unified Stadia Maps API credit pool, the same pool that covers forward geocoding, reverse geocoding, routing, and tiles. Each autocomplete request is a single billable request.

Where to Go Next

From the Blog

More on geocoding and search from the Stadia Maps blog: