Geocoding Documentation

Purpose

The LightBox Geocoding API provides access to users interested in matching addresses to geographic locations. Geocoding is performed by using the Geocoding API with the full address, a partial address or a set of parsed address fields. The geocoding API also provides type-ahead or auto-complete capability.

Swagger: OAS 3.1 Specification

API Requests

Search

Return an address based on the full-text string 'text,' where each result includes a representative point for the address and references to related parcels, structures, or assessments. If there is no exact match, this will return the best possible match. 

GET /addresses/search

Example requests

Single Address String

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/search?text=25481 Buckwood, Lake Forest, CA

https://api.lightboxre.com/v1/addresses/search?text=25481 Buckwood, Lake Forest, CA

Parsed Address Parameters

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/search?streetNumber=3840&streetName=w 213th&locality=fairview park&region=ohio&country=US&postalCode=44126

https://api.lightboxre.com/v1/addresses/search?streetNumber=3840&streetName=w 213th&locality=fairview park®&region=ohio&country=US&postalCode=44126

Parameters

Response

Media type: application/json

Autocomplete / Type Ahead

Return a set of address candidates based on autocompletion of the partial string 'text,' where each result includes a representative point for the address and references to related core objects, parcels, addresses, assessments, and structures.

GET /addresses/_autocomplete

Example requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/_autocomplete?text=25481 Buckwood

https://api.lightboxre.com/v1/addresses/_autocomplete?text=25481 Buckwood

Parameters

Response

Media type: application/json

Reverse Geocode

Return address records based on Point WKT (Well Known Text) string. 

Note: Supports both US and Canadian addresses

Examples:

• POINT(-122.40317865990883 45.585729937697515)

GET /addresses/reverse

Example requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/reverse?wkt=POINT%28-117.852723%2033.63799%29&bufferDistance=50&bufferUnit=m

https://api.lightboxre.com/v1/addresses/reverse?wkt=POINT%28-117.852723%2033.63799%29&bufferDistance=50&bufferUnit=m

Parameters

Response

Media type: application/json

API Response

{
  "$ref": "string",
  "$metadata": {
    "geogcs": {
      "epsg": "4326"
    },
    "recordSet": {
      "totalRecords": 99,
      "bbox": {
        "xMax": -105.250409,
        "xMin": -105.251916,
        "yMax": 40.023629,
        "yMin": 40.022576
      }
    }
  },
  "addresses": [
    {
      "$ref": "string",
      "id": "string",
      "$metadata": {
        "geocode": {
          "confidence": {
                "streetNumber": 1,
                "streetName": 1,
                "locality": 1,
                "postalCode": 1,
                "score": 1
              },
          "changeFlag": {
            "streetName": "Fuzzy",
            "streetType": "Added",
            "locality": "Changed",
            "postalCode": "Removed"
          },
          "addressComponents": {
            "prefixDirection": "string",
            "prefixType": "string",
            "streetNumber": "string",
            "streetName": "string",
            "suffixType": "string",
            "suffixDirection": "string",
            "unit": "string"
          },
          "aliases": [
            {
              "prefixType": null,
              "prefixDirection": null,
              "streetNumber": "4007",
              "streetName": "AR-10",
              "suffixType": null,
              "suffixDirection": null,
              "unit": null
             }
           ]                      
          "precisionCode": "10"
        }
      },
      "label": "string",
      "location": {
        "streetAddress": "string",
        "borough": "string",
        "locality": "string",
        "regionCode": "AL",
        "postalCode": "string",
        "postalCodeExt": "string",
        "countryCode": "US",
        "representativePoint": {
          "longitude": 0,
          "latitude": 0,
          "geometry": {
            "wkt": "string"
          }
        }
      },
      "parcels": [
        {
          "$ref": "string",
          "id": "string"
        }
      ],
      "structures": [
        {
          "$ref": "string",
          "id": "string"
        }
      ],
      "assessments": [
        {
          "$ref": "string",
          "id": "string"
        }
      ]
    }
  ]
}

Field Dictionary

HTTP Error Codes

Interpreting the Result

Change Flag

Change flag provides information about the matched address and how it differs from the input address. There are four parts of the address that are reported on: street name, street type, locality, and postal code. 

Confidence Score

Our API results include a confidence score, which indicates the likelihood that the address that was input was accurately matched to the correct location. High-quality input addresses are easily parsed and matched and have a high confidence score. Low-quality input addresses, such as those with significant misspellings, numerous incorrect values, conflicting values, and other issues can be parsed and matched in most cases, but the confidence score may be lower. The confidence score will have a value from 0 to 1 with 1 being the highest confidence and 0 being the lowest confidence score. 

The confidence object within the result will contain a separate score for streetNumber, streetName, locality, postalCode, and a combined score called score. Typically, looking at the score value is enough to determine if the address that was matched to is the correct address, but your business logic might use the individual scores depending on your workflow.

Example: 15 Allstate Pkwy, Markham, ON, L3R 5B4. This is a complete and perfectly parsed address that can be matched to an exact location. Entering this address in the LightBox Geocoding API returns a result with no changes and a perfect confidence score. We will examine two variations of this address below. 

Variation One: 15 Allstate St, Toronto, ON. This lacks the postal code and also contains two errors: 'street' instead of 'pkwy' and 'Toronto' instead of 'Markham.' The result would have a high, but imperfect, confidence score. 

Variation Two: 15 Allstate St, Markham Toronto, ON. This contains the errors above and an additional error—two cities. This address is not a perfect match for any existing address and could match several similar addresses in both Markham and Toronto, so the confidence score of the result will be the lowest of the three examples.

Aliases

If the address has alternate names, they will be returned under Aliases. This is represented as an array as there can be many aliases assigned to an address. If there are no aliases, then this object is returned as null.

Precision Code

Precision code is a vital piece of metadata returned by the LightBox Geocoder. The precision code represents the geo-precision of the returned latitude, longitude, and WKT geometry. The table below will explain the different codes and their descriptions.  

Address Components

These values represent the address components of the matched address.

• Geocoding Overview

• Geocoding Release Notes