Source: https://developers.woosmap.com/products/localities/guides/tuning-localities-results/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Tune Localities Autocomplete & Details ## 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 Reference](/products/localities/features/autocomplete/) and [Details Reference](/products/localities/features/details/). If you're using the Map JS API, check out the [Map JS Localities Guides](/products/localities/guides/map-js-guide/). ## 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. ```bash # 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. ```bash # 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. ```bash # 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: - `locality` - The locality type is a convenient alias that groups together many sub-types like `city`, `town`, `village`, and `suburb`. - `postal_code` - Zip/postal codes - `address` - Street addresses - `admin_level` - Administrative regions - `airport` - Airports only - `country` - Countries ```bash # 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. ```bash # 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](/products/localities/concepts/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. ```bash # 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. ```bash # 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). ```bash # 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](/products/localities/guides/integration-path/).