Vuetify Here Geocoder Autocomplete

A wrapper for the v-autocomplete component from Vuetify to use the autocomplete feature of the new HERE Geocoding & Search API

Demo

A demo is available here.

Installation

Run in your terminal:

# npm
npm install vuetify-here-geocoder-autocomplete

# Yarn
yarn add vuetify-here-geocoder-autocomplete

You also need to sign up for a free account with Here, which offers 250K transactions per month for free (starting in 2021), to generate an API key.

:warning: Warning: The autocomplete function of the HERE Geocoding & Search API is currently still in BETA state. But works fine in combination with this library. :warning:

:pushpin: Note: This library does not work with Internet Explorer because it uses the standard Javascript fetch API to communicate with the Here API. You can find more information here. If it is absolutely mandatory for you to be able to run in Internet Explorer, please create an issue and we can discuss the options.

Usage

<template
  ><v-here-geocoder-autocomplete
    :here-api-key="myHereApiKey"
    v-model="place"
    debounce-time
    clearable
  />
</template>
<script>
import VHereGeocoderAutocomplete from "vuetify-here-geocoder-autocomplete";
export default {
  name: "App",
  components: {
    VHereGeocoderAutocomplete
  },
  data() {
    return {
      place: null,
      myHereApiKey: "API_KEY" // I highly recommend you to inject the API key via an environment variable
    };
  }
};
</script>

The variable place looks like this:

{
  "title": "Deutschland, 10557, Berlin, Platz der Republik 1",
  "id": "here:af:streetsection:yS70afKYO41l5M.aTlXOQD:CgcIBCDVrstQEAEaATE",
  "resultType": "houseNumber",
  "houseNumberType": "PA",
  "address": {
    "label": "Platz der Republik 1, 10557 Berlin, Deutschland",
    "countryCode": "DEU",
    "countryName": "Deutschland",
    "stateCode": "BE",
    "state": "Berlin",
    "countyCode": "B",
    "county": "Berlin",
    "city": "Berlin",
    "district": "Tiergarten",
    "street": "Platz der Republik",
    "postalCode": "10557",
    "houseNumber": "1"
  },
  "highlight": "<b>Deutschland</b>, 10557, Berlin, <b>Platz der Republik 1</b>"
}

However, this depends on the type of search result, the fields title, id and address will always be included in the result.

The highlight field is the string that is displayed to the user and converts the highlight details provided by the API to the value of the title field. However, this field can also be set with a custom highlighting using the customHighlight property (see Custom Highlighting).

Note for initial value

If you don't store this kind of object in your application, you can still pass a plain string that is equivalent to the value title, e.g.: Deutschland, 10557, Berlin, Platz der Republik 1.

If this value is not null during the initialization of the component, it will automatically request the Here API and use the first hit.

That means if place is equal to Deutschland, 10557, Berlin, Platz der Republik 1, it will be automatically transformed to the above JSON object.

Props

Authentication Properties

One of the two properties must be defined for the component to communicate with the Here API.

| Property | Type | Default | Description | | :------------------------- | :------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | here-api-key | String | | Sign up with Here to generate a free API key | | here-bearer-o-auth-token | String | | You can obtain an OAuth token, for example, by using your backend to contact the OAuth interface of Here's Geocoding and Search API with the credentials for Here. The token obtained is then only valid for a limited time and can be passed to the frontend and this component to enable autocomplete requests. This procedure is more difficult than using the API key, but it prevents abuse of the API key, which can be extracted from the frontend and used by third parties for their own purposes at your expense.Further information Guide to get token |

Here API Query Properties

These properties can be used to directly configure the search query to the here autocomplete API. The values are inserted unchanged into the query. The documentation for the usage can be found in the API Reference in the autocomplete section.

| Property | Type | Default | Description | | :------- | :------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | at | String | null | Check the at parameter in the API Reference → Autocomplete → QUERY PARAMETERS → at | | in | String | null | Check the limit parameter in the API Reference → Autocomplete → QUERY PARAMETERS → in | | limit | Number | null | Check the in parameter in the API Reference → Autocomplete → QUERY PARAMETERS → limit | | types | String | null | Check the types parameter in the API Reference → Autocomplete → QUERY PARAMETERS → types | | lang | String | navigator.language (if available, otherwise null) | Check the lang parameter in the API Reference → Autocomplete → QUERY PARAMETERS → lang |

Filter Properties

Since the types property of the Here Autocomplete API offers only limited possibilities to build for example a country picker, the search results can be filtered by the properties contained in the search result object.

CAUTION the fields in the result objects are not always consistent. For what exactly to filter for in order to achieve the desired restriction, see the examples of the API and the API Reference.

In any case, the types property must also be set, since the filtering is based only on the 5 (default) results returned by the API.

Example: To limit the results to countries, the properties types="area" and administrative-area-type="country" must be set.

| Property | Type | Default | Description | | :----------------------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------ | | resultType | String | null | Filters for results where resultType exists in the search result object and matches the value defined here. | | houseNumberType | String | null | Filters for results where houseNumberType exists in the search result object and matches the value defined here. | | localityType | String | null | Filters for results where localityType exists in the search result object and matches the value defined here. | | administrativeAreaType | String | null | Filters for results where administrativeAreaType exists in the search result object and matches the value defined here. |

Other Properties

| Property | Type | Default | Description | | :----------------- | :------------------------------- | :----------------- | :-------------------------------------------------------------------------- | | debounceTime | Number|Boolean | false | Pass true to debounce the API requests for 250ms, or pass a custom delay. | | custom-highlight | Function | | See Custom Highlighting | | prependIcon | String | "mdi-map-marker" | Default styling, you can overwrite it like every other Vuetify property |

Furthermore, every prop from Vuetify Autocomplete component is supported, except items, search-input.sync, filter, loading, and return-object which are used internally.

Events

| Name | Description | Arguments | | ------- | ------------------------------------------------------------------------------ | ---------------------------------------- | | input | Emitted when the user selects a place | @input="onInput", onInput(place) { } | | clear | Emitted when the user click on the clear button (used with prop clearable) | @clear="onClear", onClear() { } | | error | Emitted when there is an error with the Here API | @error="onError", onError(error) { } |

Custom highlighting

You can override the default behavior of highlighted search query hits via a custom function and/or slot. When using both, the returned value of your custom highlight function will become the highlight prop in the slot.

The Here API provides the highlighting details in the form of the highlights field in each search result as seen in the Response sample in the API Reference.

For example like this:

{
  "title": "Deutschland, 10557, Berlin, Platz der Republik 1",
  "id": "here:af:streetsection:yS70afKYO41l5M.aTlXOQD:CgcIBCDVrstQEAEaATE",
  "resultType": "houseNumber",
  "houseNumberType": "PA",
  "address": {},
  "highlights": {
    "title": [
      {
        "start": 0,
        "end": 11
      },
      {
        "start": 13,
        "end": 18
      },
      {
        "start": 47,
        "end": 48
      }
    ],
    "address": {
      "label": [
        {
          "start": 0,
          "end": 18
        }
      ],
      "country": [
        {
          "start": 0,
          "end": 11
        }
      ]
    }
  }
}

This complicates the implementation by inserting for example HTML tags.

With a custom function

<v-here-geocoder-autocomplete :custom-highlight="yourCustomHighlightFunction" />

If custom highlighting is required, I highly recommend checking out the default function and understanding how highlighting is possible.

The custom highlight function gets the unmodified search result object and returns a string.

The default highlight function:

placeItem => {
  if (placeItem.highlights.title != null) {
    let ret = placeItem.title;
    // this is necessary because adding a bold tags displaces the highlight indexes delivered by the here api
    let incrementCounter = 0;
    placeItem.highlights.title.forEach(highlight => {
      ret = [
        ret.slice(0, highlight.start + incrementCounter),
        "<b>",
        ret.slice(
          highlight.start + incrementCounter,
          highlight.end + incrementCounter
        ),
        "</b>",
        ret.slice(highlight.end + incrementCounter)
      ].join("");
      // number of characters added with the bold tag
      incrementCounter += 7;
    });
    return ret;
  } else {
    return placeItem.title;
  }
};

With the slot

Note that this slot's parent element is a <v-list-tile-content>

<v-here-geocoder-autocomplete>
  <template slot="highlight" slot-scope="{ highlight }">
    <v-list-tile-title>{{ highlight }}</v-list-tile-title>
  </template>
</v-here-geocoder-autocomplete>