Community Forum

Tune Localities Autocomplete & Details

Learn how Localities API parameters shape your search results. Use filtering, biasing, and type selection to go from broad to precise queries.
  1. Tuning Your Localities Search Results
  2. Default Search Behavior
  3. Refining Autocomplete Suggestions
  4. Optimizing Details Requests
  5. Parameter Interactions
  6. Common Mistakes

Tuning Your Localities Search Results

This guide explains how to configure the Localities API for your use case, whether you need broad global search or precise, country-specific results.

For full API details, see the Autocomplete API Reference and Details API Reference. If you’re using the Map JS API, check out the Map JS Localities Guides.

Default Search Behavior

By default, a Woosmap Localities Autocomplete request gives you a global search experience. With just the required input and your API key, you’ll get suggestions for cities, towns, and postal codes worldwide. This is the baseline “ search for everything” behavior.

Shell
        # This is a broad, worldwide search for cities and postal codes matching "paris"
curl "https://api.woosmap.com/localities/autocomplete/?input=paris&private_key=YOUR_PRIVATE_API_KEY"

The following sections explain the impact of adding optional parameters to this basic request.

Refining Autocomplete Suggestions

You can tune your results using parameters like components for country filtering, or location and radius for location bias. These are especially useful for location-aware search, such as finding nearby addresses without excluding distant options.

Geographic Filtering

The components parameter lets you restrict results to specific countries, acting as a hard filter. If you want to prioritize results near a location but still allow global matches, use the location and radius parameters. This combination is ideal for location-aware search experiences, such as finding nearby cities or addresses without excluding distant options.

components: Country Filter

Creates a strict boundary that completely excludes results outside specified countries. Setting components=country:fr will return only French results, removing all global matches. This significantly improves accuracy and reduces irrelevant suggestions when you need results strictly within specific countries.

Shell
        # Without components: Returns Paris (France), Paris (Texas), Paris (Ontario), etc.
curl "https://api.woosmap.com/localities/autocomplete/?input=paris&private_key=YOUR_KEY"

# With components: Returns only Paris, France and French locations
curl "https://api.woosmap.com/localities/autocomplete/?input=paris&components=country:fr&private_key=YOUR_KEY"

location + radius: Location Bias

Prioritizes nearby results without excluding distant ones. Results within the radius appear first, but global results are still available if relevant. The default radius is 100,000 meters if not specified.

Shell
        # Biases results toward London, UK area but still allows global matches
curl "https://api.woosmap.com/localities/autocomplete/?input=westminster&location=51.5074,-0.1278&radius=50000&private_key=YOUR_KEY"

Result Types

The types parameter lets you choose what kind of results you want—localities, postal codes, addresses, airports, and more. Mix and match types to fit your needs. Use excluded_types to remove unwanted subcategories and keep your suggestions relevant.

types: Restrict Kind of Results

Completely changes the kind of results returned. The default is locality|postal_code (cities, towns, postal codes). Setting types=address shifts from places to street addresses. Common values include:

Shell
        # Default: Returns cities and postal codes
curl "https://api.woosmap.com/localities/autocomplete/?input=main&private_key=YOUR_KEY"

# Address-focused: Returns street addresses
curl "https://api.woosmap.com/localities/autocomplete/?input=main&types=address&private_key=YOUR_KEY"

# Multi-type: Combines different result types
curl "https://api.woosmap.com/localities/autocomplete/?input=london&types=locality|airport&private_key=YOUR_KEY"

excluded_types: Remove Unwanted Types

Removes unwanted subcategories from your selected types. Works as a secondary filter on top of types to remove noise from broad type categories.

Shell
        # Get localities but exclude small neighborhoods
curl "https://api.woosmap.com/localities/autocomplete/?input=downtown&types=locality&excluded_types=neighbourhood&private_key=YOUR_KEY"

Data Scope (Postal Code)

Use the data parameter to control postal code coverage: standard for Western Europe, advanced for worldwide. The extended parameter enhances locality searches by including postal codes in locality name matches, which is especially useful in select countries.

data: Postal Code Coverage

Controls the geographic scope of postal code data. Use standard (default) for Western Europe postal codes, or advanced for worldwide coverage. Advanced data may incur additional charges. For more on postal code coverage, see Postal Code Coverage.

extended

Includes postal codes in locality name searches. Set to postal_code to match localities by their postal codes. Only available for France, Monaco, Italy, Spain, Belgium, Switzerland, and Luxembourg. Changes the result format to name (postal code), admin_1, admin_0.

Customization

Set the language parameter to localize results, and use custom_description to control how suggestions appear in your UI.

language: Localized Results

Changes the language of returned suggestion text. Returns localized names where available (e.g., language=fr returns “ Londres” instead of “London”). Defaults to the browser’s Accept-Language header, fallback to English.

Shell
        # English results (default)
curl "https://api.woosmap.com/localities/autocomplete/?input=munich&private_key=YOUR_KEY"

# German results  
curl "https://api.woosmap.com/localities/autocomplete/?input=munich&language=de&private_key=YOUR_KEY"

custom_description: Custom Display Format

Controls how suggestions appear to users by customizing the description field using field placeholders. Use the format type:"{field1}, {field2}"|other_type:"{field3}" to create specific formatting for your UI.

Shell
        # Custom format showing name and country only
curl "https://api.woosmap.com/localities/autocomplete/?input=paris&custom_description=locality:%22{name}%20-%20{administrative_area_level_0}%22&private_key=YOUR_KEY"

Optimizing Details Requests

After a user selects a suggestion, the Details endpoint lets you control the response size and content. Use fields to limit the response to just coordinates, address components, or geographic shapes. The language parameter localizes address components, and cc_format lets you choose between alpha2 and alpha3 country codes.

fields: Response Size & Cost

Directly affects response size, speed, and billing cost. The default is geometry|address_components. Available fields include geometry (coordinates and location accuracy), address_components (structured address parts), and shape ( geographic boundaries for areas, not addresses).

Shell
        # Minimal response - coordinates only (fastest, lowest cost)
curl "https://api.woosmap.com/localities/details/?public_id=PUBLIC_ID&fields=geometry&private_key=YOUR_KEY"

# Full response including geographic shape
curl "https://api.woosmap.com/localities/details/?public_id=PUBLIC_ID&fields=geometry,address_components,shape&private_key=YOUR_KEY"

language: Address Component Language

Returns address parts in specified language where available. Affects address_components field translations, most useful for administrative area names and country names.

cc_format

Controls country code format in response. Use alpha2 (default) for “US”, “FR”, “GB” or alpha3 for “USA”, “FRA”, “ GBR”.

Parameter Interactions

Some parameters work together in specific ways. For example, components acts as a country filter first, then location and radius bias results within those countries. If you use types and excluded_types, the latter only removes subcategories from your selected types. Avoid using types=postal_code with extended=postal_code to prevent duplicate results.

Common Mistakes

It’s easy to over-filter by combining strict country filters with a small radius, which can return nothing. Avoid type conflicts, such as using types=postal_code with extended=postal_code. Requesting unsupported fields like shape for addresses wastes resources, and mismatching your UI language with the API language parameter can confuse users. Always use components when you know your target countries to improve accuracy.

For best practices and tips, see Integration & Setup Guide.

‹ Integration Path Migration from Google Places ›
Was this article helpful?
Have more questions? Submit a request