Data & API

Location Info Documentation

Print
Dark
Light
PDF

Location Info Documentation

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Purpose

Location Info is used to provide demographics data on the addresses found at a location. Data such as location type, whether or not the location is broadband serviceable, the residential and business unit count, and numerous other data points.

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

Query by Geometry

Query for location info records based on a geometry represented as a well-known text (WKT) string.
- POINT(-122.40317865990883 45.585729937697515)
- LINESTRING (-122.40581795357949 45.58497908445598,-122.40325376176125 45.58627054581282)
- POLYGON ((-122.4032877944377 45.58629457984625,-122.40264406427413 45.585697658341736,-122.40184476598769 45.58610686936547,-122.40244558080703 45.586688769812724,-122.4032877944377 45.58629457984625))
Query for location info records based on a point and a radius

GET /locationinfos/us/geometry

Pro Tip:

This endpoint is best used when you have an existing latitude and longitude from a third party geocoder, or when using the value of a map click/identify from a standard map control.

Example requests

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

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

Parameters

Parameter	Type	Description	Usage
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

Response

Media type: application/json

Query location info objects using the census block or census block group geoid

GET /locationinfos/_on/census/us/{id}

Example Requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/locationinfos/_on/census/us/60590626141

https://api.lightboxre.com/v1/locationinfos/_on/census/us/60590626141

Parameters

Parameter	Type	Description	Usage
id	path	census block geoid or census block group geoid	required

Response

Media type: application/json

Location Info objects by Parcel ID

Query Location Info objects by parcel identified using the Parcel LightBox ID

GET /locationinfos/_on/parcel/us/{id}

Example Requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/locationinfos/_on/parcel/us/0201MABNPDBU5D2EGP08YA

https://api.lightboxre.com/v1/locationinfos/_on/parcel/us/0201MABNPDBU5D2EGP08YA

Parameter	Type	Description	Usage
id	path	Parcel LightBox ID, e.g., 0201MABNPDBU5D2EGP08YA	required

Response

Media type: application/json

Location Info objects by Structure ID

Query Location Info objects by structure identified using the Structure LightBox ID

GET /locationinfos/_on/structure/us/{id}

Example Requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/locationinfos/_on/structure/us/050151K0AO2OYB14ZNWS7Q

https://api.lightboxre.com/v1/locationinfos/_on/structure/us/050151K0AO2OYB14ZNWS7Q

Parameter	Type	Description	Usage
id	path	Structure LightBox ID, e.g., 050151K0AO2OYB14ZNWS7Q	required

Response

Media type: application/json

Location Info objects by Address ID

Query Location Info objects by address identified using the Address LightBox ID

GET /locationinfos/_on/address/us/{id}

Example Requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/locationinfos/_on/address/us/0606ZGPRLD5KGWFYRD7QH9

https://api.lightboxre.com/v1/locationinfos/_on/address/us/0606ZGPRLD5KGWFYRD7QH9

Parameter	Type	Description	Usage
id	path	Address LightBox ID, e.g., 0606ZGPRLD5KGWFYRD7QH9	required

Response

Media type: application/json

Location Info Objects by Assessment ID

Query Location Info objects by assessment identified using the Assessment LightBox ID

GET /locationinfos/_on/assessment/us/{id}

Example Requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/locsationinfos/_on/assessment/us/0306F25KSXL0JZ4RTLPP99

https://api.lightboxre.com/v1/locationinfos/_on/assessment/us/0306F25KSXL0JZ4RTLPP99

Parameter	Type	Description	Usage
id	path	Assessment LightBox ID, e.g., 0306F25KSXL0JZ4RTLPP99	required

Response

Media type: application/json

Tile Request

Use within common map controls to show location objects as a tile overlay.

GET /locationinfos/us/tile/{zoom}/{x}/{y}

Example Requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/locationinfos/us/tile/18/45050/104888

https://api.lightboxre.com/v1/locationinfos/us/tile/18/45050/104888

Parameters

Parameter	Type	Description	Usage
zoom	path	Tile zoom level, which can be a minimum of '13' and a maximum or '21.'	required
x	path	Tile column.	required
y	path	Tile row.	required

Response

Media type: image/png

Bounding Box Request

Use within common map controls to show location objects as a bounding box request.

GET /locationinfos/us/tile?bbox=-83.0434660625,40.0198659375,-83.04070793749999,40.0226240625&width=600&height=600

Example Requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/locationinfos/us/tile?bbox=-83.0434660625,40.0198659375,-83.04070793749999,40.0226240625&width=600&height=600

https://api.lightboxre.com/v1/locationinfos/us/tile?bbox=-83.0434660625,40.0198659375,-83.04070793749999,40.0226240625&width=600&height=600

Parameters

Parameter	Type	Description	Usage
bbox	query	A bounding box expressed in the NAD83 projected coordinate system.	required
width	query	Width of the result image	required
height	query	Height of the result image	required

Response

Media type: image/png

Health Check

Health Check is an endpoint used to determine the health of this service

GET /locationinfos/health

Example Requests

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

https://api.lightboxre.com/v1/locationinfos/health

Parameters

Parameter	Type	Description	Usage
None

Response

Media type: application/json

API Response

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

{
  "$ref": "string",
  "$metadata": {
    "geogcs": {
      "epsg": 4326
    },
    "units": {
      "area": "sqm",
      "length": "m"
    },
    "recordSet": {
      "totalRecords": 99,
      "bbox": {
        "xMax": -105.250409,
        "xMin": -105.251916,
        "yMax": 40.023629,
        "yMin": 40.022576
      }
    }
  },
  "locationInfos": [
    {
      "$ref": "string",
      "id": "07040CK7XS88KIGIJILYW4",
      "fips": "06059",
      "location": {
        "countryCode": "US",
        "representativePoint": {
          "longitude": 0,
          "latitude": 0,
          "geometry": {
            "wkt": "POINT(-118.006286621 33.7783088680001)"
          }
        },
        "geometry": {
          "wkt": "POINT(-118.006286621 33.7783088680001)"
        }
      },
      "assessmentLandUse": "Single Family Residential",
      "bslType": "Residential",
      "nonBSLReason": null,
      "unitCount": {
        "business": 4,
        "residential": 6
      },
      "residentialBusinessIndicator": "Residential",
      "censusBlock": "80590105043001",
      "classification": "example",
      "isBSL": true,
      "isPrimaryAddress": true,
      "isStructure": true,
      "locationType": "1",
      "locationDescription": "1",
      "parcels": [
        {
          "$ref": "string",
          "id": "string"
        }
      ],
      "structures": [
        {
          "$ref": "string",
          "id": "string"
        }
      ],
      "addresses": [
        {
          "$ref": "string",
          "id": "string"
        }
      ]
    }
  ]
}

Field Dictionary

Field	Type	Description
$ref	string	API reference back to this object.
id	string	LightBox Location Info ID.
fips	string	Federal Information Processing (FIPS) code for the state, as well as the Federal Information Processing code for the county. The first two digits are the state code and the last three digits are the county code.
location.countryCode	string	ISO 3166 alpha-2 country code (e.g., 'US' for the United States).
location.representativePoint.longitude		A geographic coordinate that specifies the east-west position of a point on the Earth's surface, or the surface of a celestial body.
location.representativePoint.latitude	double	A geographic coordinate that specifies the north-south position of a point on the Earth's surface, or the surface of a celestial body.
location.representativePoint.geometry	double	The geometry of the location expressed in WKT (well-known text) format.
location.geometry	string	The geometry of the location expressed in WKT (well-known text) format.
assessmentLandUse	string	The assessor code describing how the parcel of land is used that the location is located on.
bslType	string	A description from a list of standardized values indicating which type of broadband-serviceable category the location falls into.
nonBSLReason	string	A description indicating why a locale is not considered broadband-serviceable.
unitCount.business	integer	The number of business units at the location.
unitCount.residential	integer	The number of residential units at the location.
residentialBusinessIndicator	string	A code indicating if the occupancy at the locale is residential or business-based.
censusBlock	string	A 15-digit code that uniquely identifies a census block using the following schema, 2-digit state fips code + 3-digit county fips code + 6-digit Census tract code + 4-digit Census block code.
classification	string	A standardized description of the type of occupancy at the locale. The location will be classified with one of four values- Business, Residential, Mixed Use, Unknown/Other.
isBSL	boolean	A true/false value to determine if the locale is broadband-serviceable or not.
isPrimaryAddress	boolean	A true/false value indicating if the address is a primary address.
isStructure	boolean	A true/false value to determine if the locale is a structure or not.
locationType	string	A coding that describes the type of locale 1 - Primary Building (building the with an address), 2 - Secondary Building (building without and address), 3 - Address Point, 4 - Parcel.
locationDescription	string	Descriptive text for the Location Type - 1 Primary Building (building the with an address), 2 - Secondary Building (building without and address), 3 - Address Point, 4 - Parcel.

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

Location Info Release Notes

Table of contents

Purpose
API Requests
API Response
Field Dictionary
HTTP Error Codes