API Reference

This page centralizes the public API surface used by the demo and notebooks.

Core modules

here_search_demo.api

class here_search_demo.api.API(credentials=None, cache=None, raise_for_status=True, options=None, log_fn=None, on_request_sent=None, testing_header=False)

Bases: object

https://docs.here.com/geocoding-and-search/reference

BASE_URL = {Endpoint.AUTOSUGGEST: 'https://autosuggest.search.hereapi.com/v1/autosuggest', Endpoint.AUTOSUGGEST_HREF: 'https://discover.search.hereapi.com/v1/discover', Endpoint.DISCOVER: 'https://discover.search.hereapi.com/v1/discover', Endpoint.LOOKUP: 'https://lookup.search.hereapi.com/v1/lookup', Endpoint.BROWSE: 'https://browse.search.hereapi.com/v1/browse', Endpoint.REVGEOCODE: 'https://revgeocode.search.hereapi.com/v1/revgeocode', Endpoint.SIGNALS: 'https://signals.search.hereapi.com/v1/signals'}
async autosuggest(session, q, latitude, longitude, polyline=None, width=None, all_along=None, x_headers=None, **kwargs)

Calls HERE Search Autosuggest endpoint

Parameters:

  • session (ClientSession) – instance of ClientSession

  • q (str) – query text

  • latitude (float) – search center latitude

  • longitude (float) – search center longitude

  • x_headers (dict | None) – Optional X-* headers (X-Request-Id, X-AS-Session-ID, …)

Param:

kwargs: additional request URL parameters

Return type:

Response

Returns:

a Response object

async autosuggest_href(session, href, polyline=None, width=None, all_along=None, x_headers=None, **kwargs)

Calls HERE Search Autosuggest href follow-up

Blindly calls Autosuggest href :type session: ClientSession :param session: instance of HTTPSession :type href: str :param href: href value returned in Autosuggest categoryQyery/chainQuery results :type x_headers: dict | None :param x_headers: Optional X-* headers (X-Request-Id, X-AS-Session-ID, …) :param: kwargs: additional request URL parameters

Return type:

Response

Returns:

a Response object

async browse(session, latitude, longitude, categories=None, food_types=None, chains=None, polyline=None, width=None, all_along=None, x_headers=None, **kwargs)

Calls HERE Search Browse endpoint

Parameters:

  • session (ClientSession) – instance of HTTPSession

  • latitude (float) – search center latitude

  • longitude (float) – search center longitude

  • categories (Sequence[str] | None) – Places category ids for filtering

  • food_types (Sequence[str] | None) – Places cuisine ids for filtering

  • chains (Sequence[str] | None) – Places chain ids for filtering

  • x_headers (dict | None) – Optional X-* headers (X-Request-Id, X-AS-Session-ID, …)

Param:

kwargs: additional request URL parameters

Return type:

Response

Returns:

a Response object

cache: dict[str, Response]
property credentials: Credentials

Return the credentials object.

async discover(session, q, latitude, longitude, polyline=None, width=None, all_along=None, x_headers=None, **kwargs)

Calls HERE Search Discover endpoint

Parameters:

  • session (ClientSession) – instance of HTTPSession

  • q (str) – query text

  • latitude (float) – search center latitude

  • longitude (float) – search center longitude

  • x_headers (dict | None) – Optional X-* headers (X-Request-Id, X-AS-Session-ID, …)

Param:

kwargs: additional request URL parameters

Return type:

Response

Returns:

a Response object

async lookup(session, id, x_headers=None, **kwargs)

Calls HERE Search Lookup for a specific id

Parameters:

  • session (ClientSession) – instance of HTTPSession

  • id (str) – location record ID

  • x_headers (dict | None) – Optional X-* headers (X-Request-Id, X-AS-Session-ID, …)

Param:

kwargs: additional request URL parameters

Return type:

Response

Returns:

a Response object

async reverse_geocode(session, latitude, longitude, x_headers=None, **kwargs)

Calls HERE Reverse Geocode for a geo position

Parameters:

  • session (ClientSession) – instance of HTTPSession

  • latitude (float) – input position latitude

  • longitude (float) – input position longitude

  • x_headers (dict | None) – Optional X-* headers (X-Request-Id, X-AS-Session-ID, …)

Param:

kwargs: additional request URL parameters

Return type:

Response

Returns:

a Response object

async signals(session, resource_id, correlation_id, rank, action, x_headers=None, **kwargs)

Calls HERE Search Signals endpoint to report a user action on a result.

Parameters:

  • session (ClientSession) – instance of HTTPSession

  • resource_id (str) – the HERE result id on which the action is performed

  • correlation_id (str) – the X-Correlation-ID from the response that produced this result

  • rank (int) – the rank of the result in its result list

  • action (str) – the action performed by the user (e.g. “here:gs:action:view”, “start”, “end”)

  • x_headers (dict | None) – Optional X-* headers (X-User-ID, …)

  • kwargs – additional body parameters (e.g. userId, asSessionId)

Return type:

Response | None

Returns:

a Response object, or None on failure

here_search_demo.widgets.app

class here_search_demo.widgets.app.OneBoxMap(credentials=None, user_profile=None, results_limit=None, suggestions_limit=None, terms_limit=None, place_taxonomy_buttons=None, extra_api_params=None, on_map=False, fuel=False, tripadvisor=False, recommendations=False, map_only=False, options=None, testing_header=False, **kwargs)

Bases: UserProfileMixin, OneBoxCore

Interactive one-box search application with map and result panels.

OneBoxMap wires text input, taxonomy shortcuts, map rendering and result/details handling into a ready-to-use demo widget.

Parameters:

  • credentials (Credentials | None) – Optional credentials provider.

  • user_profile (UserProfile | None) – Optional user profile controlling language/signals.

  • results_limit (int | None) – Max displayed results.

  • suggestions_limit (int | None) – Max displayed suggestions.

  • terms_limit (int | None) – Max displayed term buttons.

  • place_taxonomy_buttons (PlaceTaxonomyButtons | None) – Optional custom taxonomy buttons widget.

  • extra_api_params (dict | None) – Extra params forwarded to API requests.

  • on_map (bool) – Whether to display controls on map.

  • fuel (bool) – Enable fuel details.

  • tripadvisor (bool) – Enable TripAdvisor details.

  • recommendations (bool) – Enable recommendation reranking flow.

  • map_only (bool) – Hide JSON/log panels and keep map-centric layout.

  • options (APIOptions | None) – Optional prebuilt API options.

  • testing_header (bool) – Include NLP testing header for API calls.

  • kwargs – Forwarded widget/layout options.

add_result_postprocess()

Register a built-in postprocess that signals when a result list arrives.

The callback removes itself automatically after firing once, so calling remove_result_postprocess() is optional.

After calling this, await app.post_process_tasks will block until: - a submitted_text or taxonomy response has been fully processed, - any travel-time reranking task has completed, and - the map fit-bounds animation has finished.

Return type:

None

buttons_box_w: PlaceTaxonomyButtons
clear_logs()
clear_query_text()
cors_allow_user_id_header: bool = False
credentials: Credentials
credentials_properties: CredentialsLoader
default_icons = ('fa-gas-pump', 'fa-charging-station', 'fa-utensils', 'fa-bed', 'fa-parking', 'fa-euro-sign', 'fa-pizza-slice', 'fa-hamburger')
default_options = APIOptions(endpoint={<Endpoint.AUTOSUGGEST: 1>: {'show': 'details'}, <Endpoint.AUTOSUGGEST_HREF: 2>: {'show': 'ev'}, <Endpoint.DISCOVER: 3>: {'show': 'ev'}, <Endpoint.BROWSE: 5>: {'show': 'ev'}, <Endpoint.LOOKUP: 4>: {'show': 'ev'}}, lookup_has_more_details=True)
default_output_format = 'text'
default_placeholder = 'free text'
default_search_box_layout = {'width': '240px'}
default_taxonomy = example(gas(['700-7600-0000', '700-7600-0116', '700-7600-0444'], None, None), ev(['700-7600-0322', '700-7600-0323', '700-7600-0324'], None, None), eat(['100'], None, None), sleep(['500-5000'], None, None), park(['400-4300', '800-8500'], None, None), ATM(['700-7010-0108'], None, None), pizza(None, ['800-057'], None), fastfood(None, None, ['1566', '1498']))
handle_result_details(intent, lookup_resp)

Display single lookup Response details in a JSON widget Display result on responseMap Do not touch the SearchResultButtons widget :type intent: SearchIntent :param intent: the intent behind the Response instance :type lookup_resp: Response :param lookup_resp: the lookup Response instance to handle :return: None

handle_result_list(intent, resp)

Display resp in a JSON widget Display resp with intent in SearchResultButtons widget Display results on responseMap :type intent: SearchIntent :param intent: the intent behind the Response instance :type resp: Response :param resp: the Response instance to handle :return: None

handle_suggestion_list(intent, autosuggest_resp)

Display autosuggest_resp in a JSON widget Display autosuggest_resp with intent in SearchResultButtons widget Display results on responseMap Display terms suggestions in TermsButtons widget :type intent: SearchIntent :param intent: the intent behind the Response instance :type autosuggest_resp: Response :param autosuggest_resp: the Response instance to handle :return: None

log_handler: TableLogWidget | None
logger: Logger
map_only: bool
map_w: ResponseMap
property post_process_tasks

Awaitable that resolves once results are displayed, reranked, and the map fitted.

Example usage:

app.add_result_postprocess()
app.buttons_box_w.buttons[0].click()
await app.post_process_tasks
app.remove_result_postprocess()
query_box_w: SubmittableTextBox
query_terms_w: TermsButtons
remove_result_postprocess()

Deregister the callback registered by add_result_postprocess.

Return type:

None

result_buttons_w: SearchResultButtons
result_json_w: SearchResultJson | None
result_queue: Queue
routing_api_calls: int
search_api_calls: int
search_center_label_w: Label
async search_events_preprocess(session)

Send a ‘start’ signal when the app begins processing events.

Return type:

None

show()

Display the application UI in the current notebook.

This displays the internal root widget without exposing or returning the underlying display handle.

Return type:

None

state: SearchState
async stop()

Send an ‘end’ signal then stop the event loop.

triage_intent(intent, context)

Resolve an intent into a SearchEvent, handler and config.

Keeps routing declarative via TRIAGES for most kinds; only the inherently irregular “details” case is handled specially.

here_search_demo.widgets.credentials

class here_search_demo.widgets.credentials.CredentialsLoader(*args: t.Any, **kwargs: t.Any)

Bases: AnyWidget

CREDENTIAL_KEYS = ('here.token.endpoint.url', 'here.access.key.id', 'here.access.key.secret', 'here.api.key')
active_config

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

here_search_demo.api_options

class here_search_demo.api_options.APIOption(key, values)

Bases: object

Base representation of a query option contributed to one or more endpoints.

Variables:

  • key (str) – Query parameter name (for example "show" or "at").

  • values (Sequence[str]) – One or more values attached to key.

  • endpoints (list) – Endpoints where this option is valid.

  • for_more_details (bool) – Whether option implies lookup-based enrichment.

  • incompatible_with (list) – Option classes that cannot coexist with this option.

endpoints = []
for_more_details = False
incompatible_with = []
key: str
values: Sequence[str]
class here_search_demo.api_options.APIOptions(options)

Bases: object

Normalized endpoint-to-query-options map used by here_search_demo.api.API.

endpoint stores merged query parameters per endpoint where repeated values are deduplicated and joined with commas.

Variables:

  • endpoint (dict) – Mapping Endpoint -> {query_key: csv_values}.

  • lookup_has_more_details (bool) – Whether any option requires lookup enrichment.

endpoint: dict[str, dict[str, str]]
lookup_has_more_details: bool
class here_search_demo.api_options.At(latitude, longitude)

Bases: APIOption

Location center option (at=<lat>,<lon>) for search endpoints.

endpoints = (Endpoint.DISCOVER, Endpoint.AUTOSUGGEST, Endpoint.BROWSE, Endpoint.REVGEOCODE)
class here_search_demo.api_options.Details

Bases: APIOption

Request autosuggest details payload (show=details).

endpoints = (Endpoint.AUTOSUGGEST,)
class here_search_demo.api_options.EVDetails

Bases: APIOption

Request electric-vehicle details (show=ev).

endpoints = (Endpoint.AUTOSUGGEST_HREF, Endpoint.DISCOVER, Endpoint.LOOKUP, Endpoint.BROWSE)
for_more_details = True
class here_search_demo.api_options.FuelDetails

Bases: APIOption

Request fuel-station metadata (show=fuel).

endpoints = (Endpoint.AUTOSUGGEST, Endpoint.AUTOSUGGEST_HREF, Endpoint.DISCOVER, Endpoint.LOOKUP, Endpoint.BROWSE)
class here_search_demo.api_options.FuelPriceDetails

Bases: APIOption

Request fuel and fuel-price data (show=fuel,fuelPrices).

endpoints = (Endpoint.AUTOSUGGEST_HREF, Endpoint.DISCOVER, Endpoint.LOOKUP, Endpoint.BROWSE)
class here_search_demo.api_options.RecommendPlaces

Bases: APIOption

Request recommendation enrichment (with=recommendPlaces).

endpoints = (Endpoint.AUTOSUGGEST, Endpoint.AUTOSUGGEST_HREF, Endpoint.DISCOVER)
for_more_details = True
incompatible_with = [<class 'here_search_demo.api_options.Route'>]
class here_search_demo.api_options.Route(polyline, width)

Bases: APIOption

Route corridor option (route=<polyline>;w=<width>) for search endpoints.

endpoints = (Endpoint.DISCOVER, Endpoint.AUTOSUGGEST, Endpoint.BROWSE)
class here_search_demo.api_options.Triggers400

Bases: APIOption

Testing option intentionally producing an invalid show value.

endpoints = (Endpoint.AUTOSUGGEST, Endpoint.DISCOVER, Endpoint.LOOKUP, Endpoint.BROWSE)
class here_search_demo.api_options.TripadvisorDetails

Bases: APIOption

Request TripAdvisor details in responses.

endpoints = (Endpoint.AUTOSUGGEST_HREF, Endpoint.DISCOVER, Endpoint.LOOKUP, Endpoint.BROWSE)
for_more_details = True
class here_search_demo.api_options.TruckDetails

Bases: APIOption

Request truck-related metadata (show=truck).

endpoints = (Endpoint.AUTOSUGGEST, Endpoint.AUTOSUGGEST_HREF, Endpoint.DISCOVER, Endpoint.LOOKUP, Endpoint.BROWSE)
class here_search_demo.api_options.TruckFuelPriceDetails

Bases: APIOption

Request truck and fuel-price data (show=truck,fuelPrices).

endpoints = (Endpoint.AUTOSUGGEST_HREF, Endpoint.DISCOVER, Endpoint.LOOKUP, Endpoint.BROWSE)
here_search_demo.api_options.build_api_options(config, extra_options=())

Build APIOptions from base config and optional extra options.

Extra options are appended per endpoint only when applicable, then options declared as incompatible are removed.

Parameters:

  • config – Base mapping Endpoint -> sequence[APIOption].

  • extra_options – Additional options to merge into the base config.

Returns:

Normalized options container.

Return type:

APIOptions

here_search_demo.user

class here_search_demo.user.DefaultUser(**kwargs)

Bases: UserProfile

Convenience profile with positioning enabled and sharing disabled.

class here_search_demo.user.UserProfile(use_positioning, share_experience, api=None, start_position=None, api_options=None, preferred_languages=None, name=None)

Bases: object

User preferences and runtime context for one-box interactions.

The profile stores consent flags, language preferences and the latest known user position. It can resolve locale information from coordinates through reverse geocoding and lookup calls.

Variables:

  • name (str) – Human-readable profile name.

  • id (str) – Stable profile identifier derived from name and host node.

  • api (API) – API adapter used for locale lookup operations.

  • preferred_languages (dict) – Mapping of country code (or None) to language.

  • has_country_preferences (bool) – Whether country-specific preferences exist.

  • api_options (APIOptions) – Extra API options associated with this profile.

  • preferred_language (str) – Default language fallback for the profile.

  • current_latitude (float) – Latest latitude associated with the profile.

  • current_longitude (float) – Latest longitude associated with the profile.

  • current_position_country (str) – Latest resolved country code.

berlin = (52.51604, 13.37691)
current_latitude: float
current_longitude: float
current_position_country: str
default_country_code = 'DEU'
default_current_position = (52.51604, 13.37691)
default_language = 'en'
default_name = 'default'
default_profile_languages = {'default': 'en'}
get_current_language()

Return effective language for the current position context.

get_preferred_country_language(country_code)

Return preferred language for a specific country.

Falls back to the default profile entry when no country match exists.

Parameters:

country_code (str) – ISO-like country code.

Returns:

Preferred language for the country, or None.

async get_preferred_locale(latitude, longitude)

Resolve country and language for a coordinate pair.

Parameters:

  • latitude (float) – Latitude to resolve.

  • longitude (float) – Longitude to resolve.

Returns:

(country_code, language) from HERE responses.

Return type:

Tuple[str, str]

preferred_languages: dict
send_signal(body)

Send a user signal payload.

Parameters:

body (list) – Signal payload.

async set_position(latitude, longitude)

Update current position and refresh locale-derived preferences.

Parameters:

  • latitude – Current latitude.

  • longitude – Current longitude.

Returns:

Current profile instance.

Return type:

UserProfile

property share_experience

Whether the user has opted in to experience sharing.

property use_positioning

Whether the user has opted in to position usage.

Classes used in obm_*.ipynb

class here_search_demo.base.OneBoxCore(api=None, queue=None, search_center=None, language=None, results_limit=None, suggestions_limit=None, terms_limit=None, max_transient_keep=None)

Bases: object

Core async controller for one-box search workflows.

OneBoxCore consumes SearchIntent objects from queue, maps them to typed search events, executes API calls, and dispatches responses to dedicated handlers.

Subclasses typically override presentation hooks such as handle_suggestion_list(), handle_result_list(), and handle_result_details() while reusing the routing/transport pipeline.

Parameters:

  • api (API | None) – API adapter. Defaults to here_search_demo.api.API.

  • queue (Queue | None) – Intent queue consumed by run().

  • search_center (Optional[Tuple[float, float]]) – Default (lat, lon) context used by requests.

  • language (str | None) – Preferred language code for requests.

  • results_limit (int | None) – Number of results to expose to UI handlers.

  • suggestions_limit (int | None) – Number of autosuggest items to expose.

  • terms_limit (int | None) – Number of term suggestions to expose.

  • max_transient_keep (int | None) – Maximum queued transient-text intents retained.

add_postprocess(callback)

Register an async callback(intent, event, resp, session) to be called after every processed search event.

Multiple callbacks are called in registration order. Use remove_postprocess to deregister.

Example:

results_ready = asyncio.Event()

async def wait_for_results(intent, event, resp, session):
    if intent.kind in ("submitted_text", "taxonomy"):
        results_ready.set()

app.add_postprocess(wait_for_results)
app.buttons_box_w.buttons[0].click()
await results_ready.wait()
app.remove_postprocess(wait_for_results)
Return type:

None

handle_action(intent, response)

Called after an ActionSearchEvent has sent its signal for a LocationResponseItem click. No lookup was performed; response will be None.

Return type:

None

handle_empty_text_submission(intent, response)
Typically

  • called in OneBoxCore.handle_search_event()

  • associated with OneBoxCore.EmptySearchEvent via self.intent_routes

Parameters:

  • intent (SearchIntent) – Response intent

  • response (Response) – Response instance

Return type:

None

Returns:

None

handle_result_details(intent, response)
Typically

  • called in OneBoxCore.handle_search_event()

  • associated with OneBoxCore.DetailsSearchEvent via self.intent_routes

Parameters:

  • intent (SearchIntent) – Response intent

  • response (Response) – Response instance

Return type:

None

Returns:

None

handle_result_list(intent, response)
Typically

  • called in OneBoxCore.handle_search_event()

  • associated with OneBoxCore.TextSearchEvent and OneBoxCore.PlaceTaxonomySearchEvent via self.intent_routes

Parameters:

  • intent (SearchIntent) – Response intent

  • response (Response) – Response instance

Return type:

None

Returns:

None

async handle_search_event(session)

Handle a single search event and return (intent, event, response).

This helper is used by tests and subclasses; it processes one intent using the same routing as handle_search_events.

Return type:

tuple[SearchIntent, SearchEvent, Response]

async handle_search_events()

This method repeatedly waits for search events.

handle_suggestion_list(intent, response)
Typically

  • called in OneBoxCore.handle_search_event()

  • associated with OneBoxCore.PartialTextSearchEvent via self.intent_routes

Parameters:

  • intent (SearchIntent) – Response intent

  • response (Response) – Response instance

Return type:

None

Returns:

None

remove_postprocess(callback)

Remove a previously registered postprocess callback (no-op if absent).

Return type:

None

run(handle_search_events=None)

Start the background consumer task and return self.

Parameters:

handle_search_events (Optional[Callable]) – Optional coroutine factory replacing the default event loop handler.

Returns:

Running app instance.

Return type:

OneBoxCore

async search_event_postprocess(intent, event, resp, session)

Run all registered postprocess callbacks in registration order.

Return type:

None

async stop()

Wait until queue is empty and background task has finished.

In Jupyter, await app.stop() will keep the cell busy until:

  • all queued intents are processed, and

  • the consumer task has exited.

triage_intent(intent, context)

Resolve an intent into a SearchEvent, handler and config.

Keeps routing declarative via TRIAGES for most kinds; only the inherently irregular “details” case is handled specially.

Return type:

tuple[SearchEvent, Callable[[SearchIntent, Response], None], EndpointConfig | LookupConfig | NoConfig | None]

async wait_for_search_event()

Wait for the next intent, and resolve it via triage_intent.

Return type:

tuple[SearchIntent, SearchEvent, Callable[[SearchIntent, Response], None], EndpointConfig | LookupConfig | NoConfig | None]

class here_search_demo.auth.Credentials

Bases: object

Credential and token provider for HERE API requests.

The class resolves credentials from environment variables and/or local credentials files, then exposes either an API key or OAuth access token. Token values are cached and refreshed before expiration.

Environment variable precedence for API key: HERE_ACCESS_KEY_ID + HERE_ACCESS_KEY_SECRET > HERE_API_KEY > API_KEY.

Variables:

default_auth_url (str) – Default OAuth token endpoint.

property active_config: dict[str, str]

Return a credentials-loader compatible config when fully available.

apply_active_config(active_config)

Update credentials from a validated credentials-loader config mapping.

Return type:

None

property atoken: dict

Return an OAuth access token using the async transport.

This path is intended for browser runtimes (Pyodide/JupyterLite). The token is cached in memory and refreshed when close to expiry.

Returns:

OAuth access token, or None when OAuth credentials are unavailable.

Return type:

str | None

property token: str | None

Return an OAuth access token using the synchronous transport.

This path is intended for standard CPython runtimes. The token is cached in memory and refreshed when close to expiry.

Returns:

OAuth access token, or None when OAuth credentials are unavailable.

Return type:

str | None

class here_search_demo.widgets.input_text.SubmittableTextBox(queue, state, *args, **kwargs)

Bases: HBox

A ipywidgets HBox made of a SubmittableText and a lens Button

async feed(text, delay=None)

Type text programmatically into the input widget.

Useful for notebook demos/tests that simulate user typing. "\b" characters are interpreted as backspace.

Parameters:

  • text – Text sequence to inject.

  • delay (float | None) – Delay in seconds between characters. Defaults to default_simulation_delay_sec.

submit()

Programmatically trigger a submit.

class here_search_demo.widgets.input_text.SubmittableText(*args: t.Any, **kwargs: t.Any)

Bases: Text

A ipywidgets Text class enhanced with an on_submit() method

on_submit(callback, remove=False)

(Un)Register a callback to handle text submission.

Triggered when the user clicks enter.

Parameters

callback: callable

Will be called with exactly one argument: the Widget instance

remove: bool (optional)

Whether to unregister the callback

trigger_submit()

Programmatically invoke all registered submit callbacks.

This mirrors the behavior when the front-end fires a submit custom event, without reaching into private attributes from outside this subclass.

Return type:

None

class here_search_demo.widgets.input_text.TermsButtons(target_text_box, state, values=None, buttons_count=None, index=-1, layout=None)

Bases: HBox

Suggestion buttons bound to a SubmittableTextBox.

The widget renders one button per value in state.term_suggestions. Clicking a button replaces one token in the target text box and updates SearchState.

Parameters:

  • target_text_box (SubmittableTextBox) – Text widget to update when a button is clicked.

  • state (SearchState) – Shared search state carrying the current term suggestions.

  • values (list[str] | None) – Optional initial suggestions; when provided they are stored in state.term_suggestions before rendering.

  • buttons_count (int | None) – Number of buttons to create when no suggestions are available yet.

  • index (int) – Token index to replace in the target query. -1 replaces the last token, None replaces the whole query text.

  • layout (dict | None) – Optional ipywidgets layout for the button container.

class here_search_demo.widgets.input_text.PlaceTaxonomyButtons(queue, taxonomy, icons, state)

Bases: HBox

Buttons that emit taxonomy search intents.

Each button maps to one PlaceTaxonomyItem. On click, the selected taxonomy item is stored in state and a SearchIntent(kind="taxonomy", ...) is pushed to queue.

Parameters:

  • queue (Queue) – Queue receiving taxonomy intents.

  • taxonomy (PlaceTaxonomy) – Taxonomy source used to create buttons.

  • icons (Sequence[str]) – Icons/text labels paired with taxonomy items.

  • state (SearchState) – Shared search state updated with the selected taxonomy item.

class here_search_demo.widgets.state.SearchState

Bases: object

Widget-local search view state.

This object keeps presentation-oriented data that helps widgets render the current response and preserve UI interactions between updates.

class here_search_demo.widgets.util.Output(*args: t.Any, **kwargs: t.Any)

Bases: Output

class here_search_demo.widgets.output_map.ResponseMap(queue=None, state=None, search_center_handler=None, tile_opacity=0.6, **kwargs)

Bases: PositionMap, DetailsMixin, LabelsMixin

Map widget used to render search responses and selection actions.

The map displays results as GeoJSON markers, optionally adds extra labels (fuel prices / TripAdvisor), and can fit bounds to returned items. It is also interactive: marker clicks push ActionIntent instances to queue so upper layers can retrieve details or trigger detour logic.

Parameters:

  • queue (Queue | None) – Queue used for emitted intents from map interactions.

  • state (SearchState | None) – Shared state containing ranked response items.

  • search_center_handler (Callable[[tuple[float, float]], None]) – Callback invoked when the map center changes.

  • tile_opacity (float) – Base map tile opacity.

  • kwargs – Forwarded to PositionMap.

click_result(rank, *, emit_action=True, recenter=True, show_details=True)

Programmatically simulate a map click on the result at rank.

This pushes an ActionIntent to the queue and, when travel-time mode is active, draws the detour route for the clicked result.

Example:

app.map_w.click_result(6)
Return type:

None

class here_search_demo.widgets.route.RouteController(map_instance, credentials, routing_api_call_handler=None)

Bases: object

Route acquisition and rendering controller for map widgets.

The controller fetches route geometry, renders route overlays/markers, and exposes helpers used by notebooks and UI callbacks to update route start/stop/at positions and corridor width.

Parameters:

  • map_instance (PositionMap) – Map widget receiving route layers.

  • credentials (Credentials) – HERE credentials used for routing requests.

property all_along: bool

Convenience property — reads ranking_mode.all_along.

clear_detour_routes()

Remove any rendered detour overlays without touching the route.

draw_detour_routes(route_from, route_to)

Render a green polyline from current_position → result and a purple one from result → stop_position, replacing any previously shown detour routes.

draw_future_position()

Place (or remove) a semi-transparent car marker at the future position.

The marker is shown when future_position is set (i.e. mins_from_pos > 0) and removed otherwise.

property minimal_detour: bool

Convenience property — reads ranking_mode.travel_time.

on_drawn(callback)

Register callback to be called each time a route is fully drawn.

The callback receives this RouteController instance so it can inspect flexpolyline, waypoints_count, start_position, etc. Multiple callbacks may be registered; they are called in registration order.

Example:

def my_handler(route):
    print(f"Route ready: {route.waypoints_count} waypoints")

controller.on_drawn(my_handler)
Return type:

None

on_removed(callback)

Register callback to be called when a route is removed.

Return type:

None

property search_at_position: tuple[float, float] | None

Position sent as at= to the Search API.

When mins_from_pos > 0 this is the point that many minutes ahead of the origin along the route; otherwise it is the same as current_position (the car marker location).

set_current_position(latlon=None)

Set the current car position on the route.

Parameters:

latlon (tuple[float, float] | None) – (lat, lon) current position.

set_mins_from_pos(mins)

Set X minutes ahead of the origin position as the new search centre.

set_route_start(latlon)

Set the route origin marker and trigger route acquisition when complete.

Parameters:

latlon (tuple[float, float]) – (lat, lon) origin position.

set_route_stop(latlon)

Set the route destination marker and trigger route acquisition when complete.

Parameters:

latlon (tuple[float, float]) – (lat, lon) destination position.

set_route_width(width)

Set corridor width (meters) used for route geometry and rerender it.

Parameters:

width (int | None) – Corridor width in meters; None keeps/defaults width.

class here_search_demo.widgets.output_json.SearchResultJson(state=None, **kwargs)

Bases: SearchResultList

class here_search_demo.widgets.output_buttons.SearchResultButtons(widget=None, max_results_number=None, queue=None, state=None, on_result_click=None, layout=None, **kwargs)

Bases: VBox

class here_search_demo.entity.place.PlaceTaxonomyExample

Bases: object

class here_search_demo.entity.request.Request(endpoint=None, base_url=None, params=None, data=None, x_headers=None, previous_response=None)

Bases: object

Normalized HERE Search request payload.

Variables:

  • endpoint – target HERE Search endpoint enum

  • base_url – endpoint base URL

  • params – query-string parameters

  • data – optional request body (used for POST route payloads)

  • x_headers – optional request-scoped X-* headers

  • previous_response – optional previous response used for follow-up flows

property full

Return full request URL including encoded query string.

Returns:

full request URL

property key: str

Return a deterministic cache key for this request.

Returns:

cache key string derived from base URL and params

class here_search_demo.entity.endpoint.Endpoint(*values)

Bases: IntEnum

class here_search_demo.entity.intent.ActionIntent(materialization, time)

Bases: object

Intent emitted when the user clicks a result button for a LocationResponseItem.

Unlike SearchIntent(kind="details"), this intent only triggers a signals call — no lookup is performed.