Using result scoring

This tutorial demonstrates how the API returns scoring information.

Procedure

The /geocode endpoint returns scoring information, which indicates for each result how well it matches to the original query. This can be used by the customer application to accept or reject the results depending on how “expensive” the mistake is for their use case.

A free-form text query for address 240 Washington St., Boston is formulated as follows:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=240+Washington+St.%2C+Boston
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• q - Enter a free-text query.
• apiKey - Your API key.

The address is correct, has no mistakes or typos and does not contain any irrelevant content for addressing.

The response to the above request appears as follows:

{
  "items": [
    {
      "title": "240 Washington St, Boston, MA 02108-4603, United States",
      "id": "here:af:streetsection:YCY1nQWrJ5eBrHv075VVOD:CggIBCDns4LfAhABGgMyNDAoZA",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "240 Washington St, Boston, MA 02108-4603, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "MA",
        "state": "Massachusetts",
        "county": "Suffolk",
        "city": "Boston",
        "district": "Downtown Boston",
        "street": "Washington St",
        "postalCode": "02108-4603",
        "houseNumber": "240"
      },
      "position": {
        "lat": 42.35814,
        "lng": -71.05765
      },
      "access": [
        {
          "lat": 42.35815,
          "lng": -71.05788
        }
      ],
      "mapView": {
        "west": -71.05887,
        "south": 42.35724,
        "east": -71.05643,
        "north": 42.35904
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1,
          "streets": [
            1
          ],
          "houseNumber": 1
        }
      }
    },
    {
      "title": "240 Washington St, Boston, MA 02135-3508, United States",
      "id": "here:af:streetsection:6SnFDsUujYAamxhLX-Vr1D:CgcIBCDRnLAhEAEaAzI0MChk",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "240 Washington St, Boston, MA 02135-3508, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "MA",
        "state": "Massachusetts",
        "county": "Suffolk",
        "city": "Boston",
        "district": "Brighton Center",
        "street": "Washington St",
        "postalCode": "02135-3508",
        "houseNumber": "240"
      },
      "position": {
        "lat": 42.34754,
        "lng": -71.14943
      },
      "access": [
        {
          "lat": 42.34765,
          "lng": -71.14925
        }
      ],
      "mapView": {
        "west": -71.15065,
        "south": 42.34664,
        "east": -71.14821,
        "north": 42.34844
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1,
          "streets": [
            1
          ],
          "houseNumber": 1
        }
      }
    }
  ]
}

The results include scoring block, which consists of two parts:

• queryScore – a value from 0 to 1 representing the percentage of the input that matched the returned address. It is equal to 1 if all input tokens were recognized and matched. If the input query contains any additional information – name of the person, phone number or a hint to ring twice – the queryScore will be low, but the result may be correct. But low queryScore may indicate that the result does not match some relevant part of the address in the input query.
• fieldScore – values from 0 to 1 indicating how good the result field matches to the corresponding part of the query. If all the fields that are important for addressing in the country are matched with high quality, you can assume, that queryScore is low because of the additional non-address information. And the result is still confident.

Additional information

For more information about/geocode parameters, see: API Reference.