HERE Geocoding & Search API: Developer Insights & Best Practices

Throughout 2025, the HERE Slack Developer Community hosted many discussions around the HERE Geocoding & Search API v7, covering everything from structured queries and autosuggest workflows to debugging unexpected results.

While most developers quickly get started with basic geocoding, real-world implementations often introduce more nuanced questions: choosing the right endpoint, improving result relevance, handling ambiguous queries, and integrating search experiences into modern applications. This brings together frequently asked “how-to” questions from the developer community, along with practical solutions and best practices.

1. How can I retrieve city or administrative information from coordinates?

In many applications, you don’t need a full street address. Just the city, district, or region. The Reverse Geocoding endpoint allows you to filter results using the types parameter.

Example:

https://revgeocode.search.hereapi.com/v1/revgeocode?at=53.51246,25.98294&types=area&limit=1&apiKey=YOUR_API_KEY

Copy

Using types=area restricts responses to administrative areas, making it easier to extract city or regional data.

Takeaway: Use types=area when you only need administrative information. More info here

2. How can I implement address suggestions in a search box?

Autocomplete is a core feature in modern apps. For address completion, you should use the Autocomplete capability of the HERE Geocoding & Search API, which is designed to return structured address suggestions as users type.

For broader discovery use cases (like finding places or categories), the Autosuggest endpoint can also be used but it is better suited for POIs and exploratory search, not strict address entry.

Example:

https://autosuggest.search.hereapi.com/v1/autosuggest?at=52.5200,13.4050&q=resta&limit=5&apiKey=YOUR_API_KEY

Autosuggest returns:
• Addresses
• Points of interest (POIs)
• Categories

Takeaway: Use Autocomplete for structured address input (forms, checkout, delivery) & Autosuggest for broader search experiences (places, categories, discovery). More info here

3. Which endpoint should I use to search for places like restaurants or gas stations?

A common mistake is using geocoding endpoints for place search. Instead, use the Discover endpoint, which is optimized for finding places (POIs) and categories. If you’re building a search experience, you can also use Autosuggest alongside Discover:

• Autosuggest: provides real-time suggestions as users type (good for search boxes)

• Discover: retrieves actual place results based on a query

Example:

https://discover.search.hereapi.com/v1/discover?at=52.5200,13.4050 &q=restaurant&apiKey=YOUR_API_KEY

Copy

Takeaway: Use Autosuggest for suggestions and Discover for final place search results, avoid using Geocoding for POIs. More info here.

4. How can I debug unexpected geocoding results?

Short or incomplete queries often lead to surprising results.

Ways to improve accuracy:

• Include more address components

• Add city or postal code context

• Use structured queries (qq) instead of free text

Example:

(Bad query — ambiguous): https://geocode.search.hereapi.com/v1/geocode?q=Invalidenstrasse%20117&apiKey=YOUR_API_KEY

(Better query — more context): https://geocode.search.hereapi.com/v1/geocode?q=Invalidenstrasse%20117%20Berlin&apiKey=YOUR_API_KEY

(Best — structured query): https://geocode.search.hereapi.com/v1/geocode?qq=street=Invalidenstrasse;houseNumber=117;city=Berlin;country=DEU&apiKey=YOUR_API_KEY

Takeaway: More context = better results. More info here

5. What determines the ranking of geocoding results?

Result ranking depends on multiple factors:

• Query structure

• Geographic relevance

• Available address data

• Internal scoring mechanisms

Even small query changes can impact ranking.

Takeaway: Ranking is dynamic, optimize your input for better results. More info here

6. How should I structure qq queries to improve geocoding accuracy?

Structured queries can still produce unexpected results due to small input variations.

What’s happening:

• Minor spelling differences impact matches

• Scoring considers multiple fields

• Partial matches may rank higher

Best practices:

• Ensure correct spelling (especially street names)

• Avoid overloading queries with too many fields

• Test by simplifying inputs

Example:

https://geocode.search.hereapi.com/v1/geocode?qq=street=ruedebale;city=Strasbourg;postalCode=67100;country=FRA&apiKey=YOUR_API_KEY

Takeaway:Precision matters, small differences can change results significantly.

7. How should I handle queryScore inconsistencies when using both q and qq parameters?

Using both q and qq together can lead to confusing results.

What’s happening:

• Both inputs are processed together

• Conflicting or duplicate values reduce match quality

• queryScore reflects combined interpretation

Best practices:

• Prefer using either q or qq

• Use qq for structured, high-precision input

• Avoid overlapping data

Takeaway: Mixing q and qq can hurt scoring, keep inputs clean. More info here

8. How should I structure geocoding requests when validating user-entered addresses?

When working with partially structured input, developers may see incorrect matches even with filters like types=houseNumber.

What’s happening:

• Combining q and qq introduces ambiguity

• types filters categories but doesn’t enforce location

• Partial matches may rank highly

Best practices:

• Avoid mixing q and qq

• Use qq to anchor results (city/state/postal code)

• Treat types as a filter, not validation

Example:

https://geocode.search.hereapi.com/v1/geocode?qq=city=LAUREL;state=MS;postalCode=39440&types=houseNumber,city&apiKey=YOUR_API_KEY

Copy

Takeaway: For validation, rely on structured queries, not filters. More info here.

9. How should I pass secondary unit information in geocoding requests?

Addresses with non-standard unit formats (e.g., “Lot 506AE”) may not be parsed correctly.

What’s happening:

• Only normalized formats are supported (Apt, Unit, Lot, Suite)

• Non-standard formats may be ignored

• Support varies by country

Supported regions include: AUS, AUT, BRA, CAN, ESP, FRA, GBR, HKG, IDN, IND, MEX, NZL, TUR, TWN, USA

Best practices:

• Use standardized formats (e.g., “Lot 506”)

• Avoid custom suffixes

• Be aware of regional support

Example:

https://geocode.search.hereapi.com/v1/geocode?qq=houseNumber=123;street=Main%20St;city=Toronto;postalCode=M5V;country=CAN;unit=Lot%20506&apiKey=YOUR_API_KEY

Takeaway: Normalize unit data before sending requests. More info here.

10. How can I reliably extract the correct city using reverse geocoding?

Sometimes reverse geocoding returns a district instead of the expected city.

What’s happening:

• The API returns the closest administrative match

• Districts may be prioritized over cities

• types=area includes multiple levels

Best practices:

• Adjust coordinates slightly

• Cross-check with the Discover API

• Filter using localityType, more info here

Example:

https://revgeocode.search.hereapi.com/v1/revgeocode ?at=53.512599,25.988364 &types=area

Copy

Takeaway: Reverse geocoding returns the nearest match, not always the expected one.

11. How can I report incorrect or missing address data?

Developers occasionally discover incorrect or missing location data. The recommended path is to submit corrections using HERE Map Creator, which allows users to report:
• Missing addresses
• Incorrect locations
• Outdated map data

These submissions are reviewed and integrated into future map updates. You can also submit any address feedback or places information (Name, Type, Wheelchair access, Location, Phone, Email, Website, Opening times etc.), directly here.

Conclusion

The HERE Geocoding & Search API is powerful but like any search system, input quality and structure heavily influence output quality. Across all these scenarios, a few patterns stand out:

• Prefer structured queries (qq) when possible

• Avoid mixing query types unnecessarily

• Provide context (city, postal code) to improve accuracy

By applying these best practices, you’ll build more reliable, predictable, and user-friendly location experiences. And as always, the HERE Developer Community remains a valuable resource for sharing practical solutions and real-world implementation insights.