Geocoding Data Extension Documentation

Print
Dark
Light
PDF

Geocoding Data Extension Documentation

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Purpose

To provide a means for our clients to add or enhance existing address to a data extension catalog to be returned by the LightBox Geocoding API.

Features

We support the Search, parsed of unparsed endpoint using the data extension catalog
We support the Autocomplete endpoint using the data extension catalog
We support the Reverse endpoint using the extension catalog
Return the data extension ids that your account has been assigned, Prod and Staging
Add an address to a data extension catalog
Update an address within a data extension catalog
Delete an address within a data extension catalog

Requirements

The LightBox APIs are hosted in the cloud and therefore have no platform requirements. Application requirements include:

A network connection to the LightBox API server
Ability to parse JavaScript Object Notation (JSON) API responses
Secure HTTPS connection
LightBox authentication key
LightBox authentication key

Connecting your account

When your LightBox user account is created, a unique API key is also generated. The API key should be kept secret at all times and can only be used for API requests. The key is required in all API calls.

To retrieve your unique API key:

Log in to the LightBox Developer Portal
Select Apps from the menu bar
In your approved App, note your API key (under Consumer Key)

Performing API requests

All API requests must be made over secure HTTPS connections. Requests made over HTTP will fail.

The base URL of the API server that all API requests will be made to is: https://api.lightboxre.com/ followed by a version number https://api.lightboxre.com/v1

Authentication

LightBox APIs uses a token-based authentication. All requests to the LightBox APIs must be authenticated. The token to be passed via an HTTP header with key 'x-api-key' and value <Your authentication token>

Pass your unique API key in the authorization header of every LightBox API call. LightBox uses this information to authenticate your identify and determine whether you have sufficient permissions to complete the operation. curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/

API Requests

GET /addresses/dataextension/{dataExtensionId}/search

Geocode an address using a full address string or a set of parsed address values.

Note: Supports both US and Canada addresses

Example requests

Single Address String

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

https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}/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/dataextension/{dataExtensionId}/search?streetNumber=3840&streetName=w 213th&locality=fairview park&region=ohio&country=US&postalCode=44126

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

Parameters

Parameter	Type	Description	Usage
dataExtensionId	path	Data Extension Id that is retrieved through the dictionaries endpoint	required
text	query	Full or partial address string for matching. Required if the parsed fields are not being used.	optional (if parsed fields are used)
streetNumber	query	Street number of address. (Parsed field parameter)	optional (if text field is used)
streetName	query	Street name along with street type and direction. (Parsed field parameter)	optional
unit	query	Unit number of address. (Parsed field parameter)	optional
locality	query	Name of a locality/city, (Parsed field parameter)	optional
region	query	Name of a region/state/province. (Parsed field parameter)	optional
postalCode	query	Name of a postal code or zip code. (Parsed field parameter)	optional
country	query	Name of a country. (Parsed field parameter)	optional

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, address, assessment, and structures.

Note: Supports both US and Canada addresses

GET /addresses/dataextension/{dataExtensionId}/_autocomplete

Example requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}/_autocomplete?text=25481 Buckwood, Lake Forest, Ca

https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}/_autocomplete?text=25481 Buckwood

Parameters

Parameter	Type	Description	Usage
dataExtensionId	path	Data Extension Id that is retrieved through the dataextensions endpoint	required
text	query	Partial address string for autocompletion.	required
countryCode	query	Optional parameter to limit the requests to a specific country (US, CA)	optional

Response

Media type: application/json

Reverse Geocode

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

Note: Supports both US and Canada addresses

Examples:

POINT(-122.40317865990883 45.585729937697515)

GET /addresses/dataextension/{dataExtensionId}/reverse

Example requests

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

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

Parameters

Parameter	Type	Description	Usage
dataExtensionId	path	Data Extension Id that is retrieved through the dataextensions endpoint	required
wkt	query	The geometry of the location expressed in WKT format.	required
bufferDistance	query	Buffer distance expressed in 'bufferUnits'.	optional
bufferUnit	query	The unit type to apply to the buffer (e.g., m, km, ft, mi)	optional
limit	query	A number indecating how many records you would like returned when using nearest. Default = 1, Max 40	optional

Response

Media type: application/json

Retrieve Data Extension Ids

Return a set of dictionaries that has been setup within your account

GET /addresses/dataextensions

Example requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/dataextensions

https://api.lightboxre.com/v1/addresses/dataextensions

Parameters

None

Response

Media type: application/json

{
  "$ref": "string",
  "$metadata": {
    "recordSet": {
      "totalRecords": 1
    }
  },
  "dataExtensions": [
    {
      "name": "Production",
      "id": "b43c4634-738e-4d98-ad0d-d812e3f7ff1ea8d7d5dd-7a6-dd8dd"
    }
  ]
}

POST Add address to a dictionary using parsed fields

/addresses/dataextension/{dataExtensionId}

Example requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}

https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}

Parameters

Parameter	Type	Description	Usage
dataExtensionId	path	Data Extension Id that is retrieved through the dataextensions endpoint	required
JSON	request body	JSON that provides the data for the address to add. Note JSON must be well formed or a error will be triggered	required

{
    "location": {
      "streetNumber": "123",
      "streetName": "Cherry Lane",
      "locality": "Camas",
      "regionCode": "Wa",
      "postalCode": "98607",
      "postalCodeExt": null,
      "unit": null,
      "countryCode": "US",
      "representativePoint": {
        "longitude": -122.40317865990883,
        "latitude": 45.585729937697515
      }
    },
    "precisionCode": "1",
    "parcel_lids": [
    ],
    "structure_lids": [
    ],
    "assessment_lids": [
    ]
}

Response

Media type: application/json

POST Add address to a dictionary using a single text string

/addresses/dataextension/{dataExtensionId}

Example requests

curl -X POST -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}

https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}

Parameters

Parameter	Type	Description	Usage
dataExtensionId	path	Data Extension Id that is retrieved through the dataextensions endpoint	required
JSON	request body	JSON that provides the data for the address to add. Note JSON must be well formed or a error will be triggered	required

{
    "label": "124 Cherry Lane, Camas, Wa, 98607",
    "location": {
      "representativePoint": {
        "longitude": -122.40317865990883,
        "latitude": 45.585729937697515
      }
    },
    "precisionCode": "1",
    "parcel_lids": [
    ],
    "structure_lids": [
    ],
    "assessment_lids": [
    ]
}

Response

Media type: application/json

PUT Update an address using parsed fields

/addresses/dataextension/{dataExtensionId}/{addressId}

Example requests

curl -X PUT -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}/0606ZGPRLD5KGWFYRD7QH9

https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}/0606ZGPRLD5KGWFYRD7QH9

Parameters

Parameter	Type	Description	Usage
dataExtensionId	path	Data Extension Id that is retrieved through the dataextensions endpoint	required
addressId	path	LightBox Address Id	required
JSON	request body	JSON that provides the data for the address to add. Note JSON must be well formed or a error will be triggered	required

{
    "location": {
      "streetNumber": "123",
      "streetName": "Cherry Lane",
      "locality": "Camas",
      "regionCode": "Wa",
      "postalCode": "98607",
      "postalCodeExt": null,
      "unit": null,
      "countryCode": "US",
      "representativePoint": {
        "longitude": -122.40317865990883,
        "latitude": 45.585729937697515
      }
    },
    "precisionCode": "1",
    "parcel_lids": [
    ],
    "structure_lids": [
    ],
    "assessment_lids": [
    ]
}

Response

Media type: application/json

DELETE Update an address using parsed fields

/addresses/dataextension/{dataExtensionId}/{addressId}

Example requests

curl -X DELETE -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}/0606ZGPRLD5KGWFYRD7QH9

https://api.lightboxre.com/v1/addresses/dataextension/{dataExtensionId}/0606ZGPRLD5KGWFYRD7QH9

Parameters

Parameter	Type	Description	Usage
dataExtensionId	path	Data Extension Id that is retrieved through the dataextensions	required
addressId	path	LightBox Address Id	required

Response

Media type: application/json

API Response

For each endpoint other then the tile requests the response will stay consistent.

{
  "$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"
          },
          "precisionCode": "10"
        }
      },
      "label": "string",
      "location": {
        "streetAddress": "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

Field	Type	Description

HTTP Error Codes

HTTP Response status codes along with a brief summary of their commonly accepted usage. These status codes are returned by LightBox APIs for each request:

200	The request succeeded.
201	The object was created successfully
202	Accepted, no content
204	Successful, no content
204	The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. Typically returned on a DELETE
400	One or more of the request parameters were invalid.
401	The client must authenticate itself to get the requested response. *Note:* This could also be due to your trial key has expired.
404	The server cannot find the requested resource. This can also mean that the endpoint is valid but the resource itself does not exist.
429	Too many requests were made in a short period of time, or you have exceeded your request-lot pool.
500	The server has encountered an error it does not know how to handle.
503	Service Unavailable.

Was this article helpful?

What's Next

Geocoding Data Extension Release Notes

Table of contents

Purpose
Features
API Requests
API Response
Field Dictionary
HTTP Error Codes