vuetify-here-geocoder-autocomplete

    1.1.0 • Public • Published

    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

    GitHub Workflow Status (branch) Codecov branch VueJS 2.x npm GitHub

    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": "<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>

    Install

    npm i vuetify-here-geocoder-autocomplete

    DownloadsWeekly Downloads

    4

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    1.5 MB

    Total Files

    6

    Last publish

    Collaborators

    • philter