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: The autocomplete function of the HERE Geocoding & Search API is currently still in BETA state. But works fine in combination with this library. ⚠️

📌 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": "Deutschland, 10557, Berlin, Platz der Republik 1"
}

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.

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.

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.

Other Properties

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

Events

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),
        "",
        ret.slice(
          highlight.start + incrementCounter,
          highlight.end + incrementCounter
        ),
        "",
        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-here-geocoder-autocomplete>
  <template slot="highlight" slot-scope="{ highlight }">
    <v-list-tile-title>{{ highlight }}v-list-tile-title>
  template>
v-here-geocoder-autocomplete>