Information on how a request was parsed

WARNING

The parsing feature is in BETA state.

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

Authorization: Bearer [your token]

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.

WARNING

New types of elements of the parsing block can get added to the list without further notice. Applications using HERE Geocoding and Search must not assume the list is fixed.

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

Authorization: Bearer [your token]

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.

More details about /geocode parameters can be found in the API Reference.

results matching ""

    No results matching ""