Vicinity titles

What is a vicinity title?

Every result displayed by the demo — both the result buttons in the sidebar and the map marker labels — shows a short human-readable label that we call the vicinity title. It is derived from the raw HERE Geocoder / Autosuggest response and may differ from the item’s title field.

Where the title field comes from

The HERE Search API returns a title string for every result item. For place results this is the POI or venue name (e.g. "McDonald's"). For street / address / locality results it is the full address label or the place name at the matched level (e.g. "Rue de Rivoli", "10th Arrondissement").

How vicinity titles differ

The result buttons and map labels use a disambiguated label instead of the raw title. The disambiguation is computed by _get_vicinity() in src/here_search_demo/widgets/state.py.

Source material

Labels are built from the address.label string of each item. That field contains a comma-separated address hierarchy, e.g.

McDonald's, 1 Rue de Rivoli, 1st Arrondissement, Paris, France

Split on ", " this becomes the parts list:

index

value

0

McDonald's

1

1 Rue de Rivoli

2

1st Arrondissement

3

Paris

4

France

parts[0] (the place name) is always shown. Extra parts are added only as needed to make the label unique within the current result set.

Multi-item disambiguation

When a result set contains several items that share the same parts[0] (e.g. multiple "McDonald's" branches), the algorithm progressively adds address parts right-to-left (state → city → street → …) until every label is unique:

  1. Multi-country sets — if items come from different countries, the country (parts[-1]) is pre-appended for all items so that "McDonald's, Germany" is immediately shown alongside "McDonald's, France".

  2. Single-country sets — intermediate parts (parts[-2], parts[-3], …, parts[1]) are tried in that order; the country is added as a last resort.

Parts are always rendered in their original left-to-right address order regardless of the order they were selected.

Bracketed-title exception

When item["title"] itself already contains a parenthetical expression (detected by the regex \(.*?\)), the title is used verbatim as the display label. The item does not participate in the disambiguation loop and its address parts are never appended.

Rationale: parenthetical text in a title is part of the official venue name or branding (e.g. "Post Office (Main Branch)", "Starbucks (Airport Terminal)", "The George (Pub)"). Appending address parts would create redundant and confusing labels, and such titles are already self-identifying within normal result sets.

Example:

item["title"]

vicinity title

address suffix added?

"Starbucks"

"Starbucks, Centrum"

yes (disambiguation)

"Starbucks (Airport)"

"Starbucks (Airport)"

no (exception)

_vicinity field

After _get_vicinity() runs, each item dict gets a _vicinity key whose value is the list of address parts that make up the display label. For a non-bracketed item with label "McDonald's, Paris" it would be ["McDonald's", "Paris"]. For a bracketed item it is always the single- element list ["<title>"].

_vicinity is:

  • used by the map marker labels to split the label across two lines (name on the first line, vicinity qualifier on the second);

  • copied into the JSON output widget so the computed label is visible alongside the raw API response for debugging.

Query / category suggestion items

Items of type chainQuery or categoryQuery (returned by the Autosuggest endpoint) are left untouched. Their title field is used as-is and no _vicinity key is set.