Formulate a qualified query

This tutorial demonstrates how to use qualified queries.

Procedure

Qualified address input for the /geocode endpoint is an option when the address text is captured in separate fields. For instance, as part of a sign-up process or whenever structured input is a requirement.

For example, an address "425 W Randolph St, Chicago, IL 60606, United States" can be qualified as the following set of sub-parameters:

• houseNumber=425
• street=W Randolph St
• city=Chicago
• state=IL
• postalCode=60606
• country=United States

Note that country in this case is a qualified field of an address, which supports a single country name or upper-case country code. To limit the results by a list of upper-case ISO 3166-1 alpha-3 country codes, please use the in parameter.

The query can be formulated with the following:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?qq=
        houseNumber=425;
        street=W+Randolph+St;
        city=Chicago;
        state=IL;
        postalCode=60606;
        country=United+States
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• qq - Enter a qualified query. A qualified query is similar to a free-text query, but in a structured manner. It can take multiple sub-parameters, separated by semicolon, allowing to specify different aspects of a query.
• apiKey - Your API key.

The response to the above request looks like the following:

{
  "items": [
    {
      "title": "425 W Randolph St, Chicago, IL 60606-1506, United States",
      "id": "here:af:streetsection:hdZ6xBRUraY46IQZCqZidD:CgcIBCDMlOElEAEaAzQyNShk",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "425 W Randolph St, Chicago, IL 60606-1506, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "IL",
        "state": "Illinois",
        "county": "Cook",
        "city": "Chicago",
        "district": "West Loop",
        "street": "W Randolph St",
        "postalCode": "60606-1506",
        "houseNumber": "425"
      },
      "position": {
        "lat": 41.88432,
        "lng": -87.63877
      },
      "access": [
        {
          "lat": 41.88449,
          "lng": -87.63877
        }
      ],
      "mapView": {
        "west": -87.63998,
        "south": 41.88342,
        "east": -87.63756,
        "north": 41.88522
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "country": 1,
          "state": 1,
          "city": 1,
          "streets": [
            1
          ],
          "houseNumber": 1,
          "postalCode": 1
        }
      }
    }
  ]
}

The /geocode endpoint also supports a street name and a house number joined into an address line. The address line can be specified with sub-parameter street

The above query can also be formulated with the following:

• street=425 W Randolph St
• city=Chicago
• state=IL
• postalCode=60606
• country=United States

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?qq=
        street=425+W+Randolph+St;
        city=Chicago;
        state=IL;
        postalCode=60606;
        country=United+States
    &apiKey={YOUR_API_KEY}

Additional information

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