How to set geocoding parameters

The Search & Geocoding API 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.

• 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 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.

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.

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. 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 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.