How to request and use parsing information

This tutorial demonstrates how to get information on how a request was parsed.

Procedure

The /geocode endpoint can provide information about how it parsed a request. Applications can use the information to decide whether a request requires further processing or not. Applications can also use the information for address cleansing, for example, to increase the Geocoder success rate and confidence level for future geocoding requests.

To activate the feature use the parameter show=parsing:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Unit+3+76+Sixth+Av+KEDRON
    &show=parsing
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• q - Enter a free-text query.
• show - Select additional fields to be rendered in the response.
• apiKey - Your API key.

The response to the above request looks like the following:

{
  "items": [
    {
      "title": "76 Sixth Ave, Kedron QLD 4031, Australia",
      "id": "here:af:streetsection:XqjAl1dxDSkrHJXjoG-qHD:CggIBCCm0Z2fARABGgI3Nihk",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "76 Sixth Ave, Kedron QLD 4031, Australia",
        "countryCode": "AUS",
        "countryName": "Australia",
        "stateCode": "QLD",
        "state": "Queensland",
        "city": "Brisbane",
        "district": "Kedron",
        "street": "Sixth Ave",
        "postalCode": "4031",
        "houseNumber": "76"
      },
      "position": {
        "lat": -27.40998,
        "lng": 153.03874
      },
      "access": [
        {
          "lat": -27.41005,
          "lng": 153.03869
        }
      ],
      "mapView": {
        "west": 153.03773,
        "south": -27.41088,
        "east": 153.03975,
        "north": -27.40908
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "district": 1,
          "streets": [
            1
          ],
          "houseNumber": 1,
          "unit": 1
        }
      },
      "parsing": {
        "district": [
          {
            "start": 19,
            "end": 25,
            "value": "KEDRON"
          }
        ],
        "street": [
          {
            "start": 10,
            "end": 18,
            "value": "Sixth Av"
          }
        ],
        "houseNumber": [
          {
            "start": 7,
            "end": 9,
            "value": "76"
          }
        ],
        "secondaryUnits": [
          {
            "start": 0,
            "end": 6,
            "value": "Unit 3"
          }
        ]
      }
    }
  ]
}

The result item includes the block named parsing.

In this example, the query contains terms that the /geocode matches to district, street and houseNumber fields. The parsing block lists all the matched fields and for each of them the value and the reference to the corresponding terms in the query.

For each of the parsed request elements the parsing block includes:

• start - first index of the matched range (0-based indexing, inclusive)
• end - one position past the last index of the matched range (0-based indexing, exclusive). The difference between end and start gives the length of the term
• value - matched term in the input string. They are shown exactly as is in the query. In this example in the query the street type is abbreviated as "Av": Sixth+Av, which is different from the standardized street type abbreviation in the response Sixth Ave

The parsing block may include parsing information for all the same address components as in the address block in the response.

The parsing block may also include information about the parts of the query that has been recognized by the /geocode but do not match to the address components. Currently /geocode supports only one type of such information: secondary unit designators, like apartment, unit, floor. In this example it is Unit 3.

In case of qualified or hybrid queries, the parsing blocks also include the names of the corresponding qualified fields.

The following is a hybrid query with freeform text plus a qualified field:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Unit+3+76+Sixth+Av+KEDRON
    &&qq=state%3DQueensland
    &show=parsing
    &apiKey={YOUR_API_KEY}

The response to the above request looks like the following:

{
  "items": [
    {
      "title": "76 Sixth Ave, Kedron QLD 4031, Australia",
      "id": "here:af:streetsection:XqjAl1dxDSkrHJXjoG-qHD:CggIBCCm0Z2fARABGgI3Nihk",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "76 Sixth Ave, Kedron QLD 4031, Australia",
        "countryCode": "AUS",
        "countryName": "Australia",
        "stateCode": "QLD",
        "state": "Queensland",
        "city": "Brisbane",
        "district": "Kedron",
        "street": "Sixth Ave",
        "postalCode": "4031",
        "houseNumber": "76"
      },
      "position": {
        "lat": -27.40998,
        "lng": 153.03874
      },
      "access": [
        {
          "lat": -27.41005,
          "lng": 153.03869
        }
      ],
      "mapView": {
        "west": 153.03773,
        "south": -27.41088,
        "east": 153.03975,
        "north": -27.40908
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "state": 1,
          "district": 1,
          "streets": [
            1
          ],
          "houseNumber": 1,
          "unit": 1
        }
      },
      "parsing": {
        "state": [
          {
            "start": 0,
            "end": 10,
            "value": "Queensland",
            "qq": "state"
          }
        ],
        "district": [
          {
            "start": 19,
            "end": 25,
            "value": "KEDRON"
          }
        ],
        "street": [
          {
            "start": 10,
            "end": 18,
            "value": "Sixth Av"
          }
        ],
        "houseNumber": [
          {
            "start": 7,
            "end": 9,
            "value": "76"
          }
        ],
        "secondaryUnits": [
          {
            "start": 0,
            "end": 6,
            "value": "Unit 3"
          }
        ]
      }
    }
  ]
}

Parsing information for the state includes the additional field qq, which refers to state.

Additional information

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