---
title: "How to set geocoding parameters | Guides"
description: "Configure geocoding parameters for better results and understand search logic."
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# How to set geocoding parameters

The [Search & Geocoding API](https://docs.maptiler.com/cloud/api/geocoding/) provides parameters to control search results and fine-tune geocoding behavior. This guide explains how the geocoding engine processes the search queries and how you can configure the parameters for optimal results.

## How geocoding works

When you send a query to the Geocoding API, the engine processes the string through a multi-step parsing and hierarchical matching system rather than performing a simple database lookup.

-   **The parser:** Splits the input string into logical components (house numbers, street names, cities, postal codes, countries) across all indexes simultaneously. The engine evaluates these combinations and applies penalties for illogical or inconsistent pairings.
-   **The hierarchy:** Uses a specific-to-general fallback approach: It searches for an exact address point first. If the specific house number is missing, it returns the street centroid. If the street is not found, it falls back to the city, region, and finally the country.

## Core search query parameters

These are the basic parameters you can use to configure the search service and get the results your users expect.

### country

Limits searches to specific countries. Specify one or more countries using comma-separated [ISO 3166-1 **alpha-2** country codes](https://www.iso.org/obp/ui/#search).

-   **Example:** Set `country=no` when searching for places in Norway to exclude matches for Oslo in Minnesota, USA.
-   **Parsing impact:** Setting `country=us` together with `language=en` activates a specialized parsing mechanism tailored for US address formats.

### bbox

Restricts search results to a geographic bounding box defined as `[west, south, east, north]`. Features outside this area are excluded entirely.

-   **Example:** Set a bounding box around New York City to filter out global results for common names like “London”.

### proximity

Biases search results toward a specific coordinate point or a user’s location via server-side IP detection (`proximity=ip`).

-   **Behavior:** Prioritizes results closer to the specified location without completely excluding relevant global matches. For example, a user in Texas searching for “Paris” with proximity enabled will see Paris, Texas ranked higher than Paris, France.

### types

Filters results to include only specific feature types. Multiple values can be comma-separated. See the [PlaceType values](https://docs.maptiler.com/guides/location-services/geocoding-search/place-types-values/) in the API reference for accepted options.

Administrative hierarchies vary significantly by country, making a universal classification challenging. MapTiler Geocoding defines a global hierarchy mapped by best effort. Consider the structural differences between administrative boundaries and populated places:

-   **Municipality (`municipality`):** Represents a legal administrative jurisdiction. These boundaries can cover large rural areas or forests, meaning the geometric centroid of a municipality might sit far away from the residential center.
-   **Populated places (`city`, `town`, `village`):** Represents the actual built-up residential areas where people live.

For **global applications**, keep multiple index types enabled (such as `region,subregion,county,municipality`) instead of filtering down to a single type. For **local applications**, test which hierarchy level aligns best with regional expectations and filter out unnecessary types to reduce noise.

Tip

To find the exact classification from the source data regardless of the index used, check the `properties.place_designation` field in the API response.

### autocomplete

Controls whether the engine treats the query as a partial input (`true`, default) or a finalized statement (`false`).

-   **`autocomplete=true`:** Optimized for interactive search bars. The engine predicts the remaining text (typing “Lon” suggests “London”).
-   **`autocomplete=false`:** Optimized for batch geocoding or processing completed databases. The engine looks for exact matches and avoids guessing popular completions.

Warning

When autocomplete is enabled, **every user keystroke triggers a separate API request**. To control the total request volume, we recommend that you implement the search using our [SDK JS Geocoding control module](https://docs.maptiler.com/sdk-js/modules/geocoding/), which ensures that your geocoding service usage is tracked [by session](https://docs.maptiler.com/guides/account/sessions-vs-requests/#sessions). If you need to use another library or access the API directly, then your usage is tracked [by request](https://docs.maptiler.com/guides/account/sessions-vs-requests/#requests); in that case you can configure your front-end application to call the API only after a minimum character threshold is reached to reduce the number of API requests.

### fuzzyMatch

Determines whether the engine allows approximate matching (`true`, default) or enforces strict exact matching (`false`).

-   **`fuzzyMatch=true`:** Tolerates typos, misspellings, and phonetic variations (searching for “wahsington” returns “Washington, DC”). Recommended for standard user search inputs.
-   **`fuzzyMatch=false`:** Requires precise spelling. Use this for automated systems or strict data validation where input accuracy is guaranteed.

### language

Prioritizes results in the specified language using [ISO 639-1 codes](https://en.wikipedia.org/wiki/ISO_639-1). It also provides format hinting to help the parser recognize regional address structures.

-   **Format hinting:** In English (`en`), addresses generally follow a `[Number] [Street]` format, whereas German (`de`) often uses `[Street] [Number]`. Setting the correct language helps the parser identify components accurately.
-   **Ranking behavior:** Specifying a language can lower the ranking of features that lack a translation in that language. If an expected result is missing, try removing the language parameter.

### limit

Controls the maximum number of results returned. The default value is `5` and the maximum supported value is `10`.

## Regional address handling

Address formats and datasets differ across regions. The engine applies specific rules based on the target area:

-   **United States:** Combines direct government data feeds (including New York, Texas, and Florida counties) with OpenAddresses, OpenStreetMap, and TIGER data. The engine automatically handles common abbreviations (such as `St` vs `Street`) and ordinals (`9th` vs `Ninth`), removing the need for manual text normalization.
-   **Europe:** Handles compound street names common in languages like German or Dutch (e.g., `Bahnhofstrasse`) via fuzzy text splitting. Queries rely heavily on city names and postcodes to distinguish identical street names in adjacent settlements.
-   **Alphanumeric house numbers:** Supports special formatting characters globally, including slashes, dashes, and letters (e.g., `10/2`, `10-2`, `10a`, `10 bis`).

## Points of interest (POI)

By default, the Geocoding API focuses primarily on geographic places and address points. To include [points of interest](https://wiki.openstreetmap.org/wiki/Points_of_interest) in the search results, you need to explicitly enable this option.

-   **How to enable:** Append `poi` to the `types` parameter. Example: `types=address,poi`
-   **Limitations:** The API only supports searching for POIs by _name_ (“Eiffel Tower”). Searching by _category_ (“restaurants near me”) is not supported yet.

## Troubleshooting

If a query does not return the expected results, check the following components:

-   **Relevance score:** Review the `relevance` field in the JSON response. A value below `0.5` indicates a fuzzy match or a fallback result, such as a street centroid instead of a specific house number.
-   **Missing addresses:** New constructions might not appear in the index immediately, as datasets follow a monthly update cycle.
-   **Parsing alignment:** Ensure your query structure mirrors the typical address layout of the target region to help the parser identify components cleanly.