.png?sv=2022-11-02&spr=https&st=2024-12-04T08%3A49%3A34Z&se=2024-12-04T08%3A59%3A34Z&sr=c&sp=r&sig=aI%2B7uQXr4xtXpcw4Ev1jeGDx20jkAgCoK99Iz5J66rw%3D){kind=logo}
Structures Documentation
- Print
- DarkLight
- PDF
Structures Documentation
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Purpose
The LightBox Structure API provides access to the LightBox National Structure database. This key dataset is a foundational layer in the LightBox SmartFabric™ data product.
Features
- Return structures that intersect a geometry.
- Return all structures that are related to a parcel boundary.
- Add structure tile layer to your favorite map control.
- Return the structure based on a LightBox ID or a Building UBID.
- The ability to style parcel boundaries, color, fill, weight, and opacity. This allows you to apply your brand to the display of parcel boundaries within a mapping experience.
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 structure 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))
GET /structures/{countryCode}/geometry
Pro Tip:
This endpoint is best used when you have an existing latitude and longitude from a third-party geocoder, or when you are 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/structures/us/geometry?wkt=POINT%28-117.852723%2033.63799%29&bufferDistance=50&bufferUnit=m
https://api.lightboxre.com/v1/structures/us/geometry?wkt=POINT%28-117.852723%2033.63799%29&bufferDistance=50&bufferUnit=m
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| countryCode | path | ISO 3166 alpha-2 country code (e.g., 'US' for the United States). | required |
| wkt | query | The geometry of the location is 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 | Limit the number of records returned. Used in pagination along with offset to page through a large result set. | optional |
| offset | query | Offset from the first record (0). Used in pagination along with limit to page through a large result set. | optional |
Response
Media type: application/json
Query By Address
Query structures by address.
GET /structures/address
Pro Tip:
You can use this endpoint as a one request vs a double request, first to the Geocoder then to Structures, based on the LightBox Structure ID. Note: If the address entered is not related to a structure, you will receive a 404 Not Found HTTP Response.
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/address?text=5201%20California%20Ave%2C%20Irvine%20CA
https://api.lightboxre.com/v1/structures/address?text=5201%20California%20Ave%2C%20Irvine%20CA
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| text | query | Complete address string. | required |
Response
Media type: application/json
Query by LightBox ID
Query structures using the LightBox Parcel 'ID.'
GET /structures/{countryCode}/{id}
Pro Tip:
- A lot of our endpoints end with a single path parameter of ID. When the LightBox ID is supported then it is that ID, but for some resources the ID can be a FIPS code as it is for county, or a state abbreviation, as it is with state.
- LightBox IDs are also returned from many resources. For example, Geocoding will return the LightBox ID for Parcel, Structure and Assessment.
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/us/0501C58EX3CFSULTYW1HR0
https://api.lightboxre.com/v1/structures/us/0501C58EX3CFSULTYW1HR0
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| id | path | Structure LightBox ID. | required |
| countryCode | path | ISO 3166 alpha-2 country code (e.g., 'US' for the United States). | required |
Response
Media type: application/json
Query by Universal Building ID (UBID)
Query structures using the Universal Building 'ID.'
GET /structures/{countryCode}/ubid/{UBID}
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/us/ubid/8554J4QX+7F6-13-13-12-12
https://api.lightboxre.com/v1/structures/us/ubid/8554J4QX+7F6-13-13-12-12
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| ubid | path | Universal Building ID. | required |
| countryCode | path | ISO 3166 alpha-2 country code (e.g., 'US' for the United States). | required |
Response
Media type: application/json
Query for all structures that are on a parcel
Query structures that are on a parcel oe parcels using the LightBox Parcel 'ID.'
GET /structures/_on/parcel/{countryCode}/{id}
Pro Tip:
- Most LightBox API endpoints end with a single path parameter of ID. When the LightBox ID is supported then it is that ID, but for some resources the ID could be a FIPS code as it is for county, or a state abbreviation, as it is with state.
- LightBox IDs are also returned from many resources. Geocoding is a great example which will return the LightBox ID for Parcel, Structure and Assessment.
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/_on/parcel/us/0201MABNPDBU5D2EGP08YA
https://api.lightboxre.com/v1/structures/_on/parcel/us/0201MABNPDBU5D2EGP08YA
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| id | path | Parcel LightBox ID. | required |
| countryCode | path | ISO 3166 alpha-2 country code (e.g., 'US' for the United States). | required |
Response
Media type: application/json
Structures by LightBox Assessment ID
Return structures that contain the assessment identified by the LightBox Assessment 'ID.'
GET /structures/_on/assessment/us/{id}
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/_on/assessment/us/030022BT8WGISNVQJIEW54
https://api.lightboxre.com/v1/structures/_on/assessment/us/030022BT8WGISNVQJIEW54
| Parameter | Type | Description | Usage |
|---|---|---|---|
| id | path | An Assessment LightBox ID | required |
Response
Media type: application/json
Structures by LightBox Address ID
Return structures that contain the assessment identified by the LightBox Address 'ID.'
GET /structures/_on/address/us/{id}
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/_on/address/us/0606ZGPRLD5KGWFYRD7QH9
https://api.lightboxre.com/v1/structures/_on/address/us/0606ZGPRLD5KGWFYRD7QH9
| Parameter | Type | Description | Usage |
|---|---|---|---|
| id | path | An Address LightBox ID | required |
Response
Media type: application/json
Structure by LightBox LocationInfo ID
Return structures that contain the LocationInfo object identified by the LightBox LocationInfo 'ID.'
GET /structures/_on/locationinfo/us/{id}
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/_on/locationinfo/us/07040CK7XS88KIGIJILYW4
https://api.lightboxre.com/v1/structures/_on/locationinfo/us/07040CK7XS88KIGIJILYW4
| Parameter | Type | Description | Usage |
|---|---|---|---|
| id | path | LocationInfo LightBox ID | required |
Response
Media type: application/json
Structure by LightBox Site ID
Return structures that contain the site object identified by the LightBox Site 'ID.'
GET /structures/_on/site/us/{id}
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/_on/site/us/0904YD6NQEZ3DPCJJG3E6U
https://api.lightboxre.com/v1/structures/_on/site/us/0904YD6NQEZ3DPCJJG3E6U
| Parameter | Type | Description | Usage |
|---|---|---|---|
| id | path | Site LightBox ID | required |
Response
Media type: application/json
Structure WMS Endpoint
Use within mapping systems that support OGC WMS Standard
GET /wms/structures/us?apikey={your api key}
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1//wms/structures/us?apikey={your api key}
https://api.lightboxre.com/v1/wms/structures/us?apikey={your api key}
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| apikey | query | Your LightBox API Authentication | required |
Response
Media type: XML/json/image
Structure Tile Endpoint
Use within common map controls to show parcel boundaries as a tile overlay.
GET /structures/{countryCode}/tile/{zoom}/{x}/{y}
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/us/tile/18/45050/104888
https://api.lightboxre.com/v1/structures/us/tile/18/45050/104888
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| countryCode | path | ISO 3166 alpha-2 country code (e.g., 'US' for the United States). | required |
| 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 |
| color | query | Line color represented in RGB format. | optional |
| fill | query | Fill color represented in RGB format. | optional |
| weight | query | Line weight represented in a number 1-10 with 1 being thin and 10 being thick. | optional |
| opacity | query | Fill color opacity values 0-100 with 0 beingtransparent and 100 being opaque. | optional |
| id | query | This parameter allows you to pass in a LightBox Structure ID or ids separated by a comma so that only those structures are displayed. | optional |
Pro Tip:
Using the query parameter id allows you to isolate a single record to be displayed. This is typically used to mimic a highlight event by adding an additional tile layer on a map control with a single record isolated and displayed in a different color.
Response
Media type: image/png
Structure Tile Bounding Box Endpoint
Use within common map controls to show parcel boundaries as a bounding box overlay.
GET /structures/{countryCode}/tile
Example Requests
curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/structures/us/tile?bbox=-83.0434660625,40.0198659375,-83.04070793749999,40.0226240625&width=600&height=600
https://api.lightboxre.com/v1/structures/us/tile?bbox=-83.0434660625,40.0198659375,-83.04070793749999,40.0226240625&width=600&height=600
Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
| countryCode | path | ISO 3166 alpha-2 country code (e.g., 'us' for the United States). | required |
| 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 |
| color | query | Line color represented in RGB format. | optional |
| fill | query | Fill color represented in RGB format. | optional |
| weight | query | Line weight represented in a number 1-10 with 1 being thin and 10 being thick. | optional |
| opacity | query | Fill color opacity values 0-100 with 0 beingtransparent and 100 being opaque. | optional |
| id | query | This parameter allows you to pass in a LightBox Parcel ID or ids separated by a comma so that only those parcels are displayed. | optional |
Response
Media type: image/png
API Response
For each endpoint other than the tile requests and health check, the response will stay consistent.
{
"$ref": "string",
"$metadata": {
"geogcs": {
"epsg": "4326"
},
"recordSet": {
"totalRecords": 99,
"limit: 100,
"offset: 10,
"bbox": {
"xMax": -105.250409,
"xMin": -105.251916,
"yMax": 40.023629,
"yMin": 40.022576
}
},
"units": {
"length": "ft",
"area": "sqft"
}
},
"structures": [
{
"$ref": "string",
"fips": "06059",
"ubid": "87G7MV2G+CW5-15-48-19-40",
"id": "string",
"$metadata": {
"geocode": {
"confidence": {
"streetNumber": 1,
"streetName": 1,
"locality": 1,
"postalCode": 1,
"score": 1
},
"precisionCode": 0
}
},
"location": {
"streetAddress": "string",
"locality": "string",
"regionCode": "AL",
"postalCode": "string",
"postalCodeExt": "string",
"unit": "string",
"countryCode": "US",
"representativePoint": {
"longitude": 0,
"latitude": 0,
"geometry": {
"wkt": "string"
}
},
"geometry": {
"wkt": "string"
}
},
"physicalFeatures": {
"height": {
"average": 0,
"max": 0,
"min": 0
},
"groundElevation": {
"average": 0,
"max": 0,
"min": 0
},
"area": {
"footprintArea": 0
},
"numberOfStories": 5.0
},
"propertyClass": "string",
"parcelCount": 0,
"business": true,
"parcels": [
{
"$ref": "string",
"id": "string"
"primaryBuilding" : true
}
]
}
]
}Field Dictionary
| Field | Type | Description |
|---|---|---|
| ubid | string | Universal building ID. |
| id | string | LightBox ID for this structure. |
| location.streetAddress | string | Street address, which comprises street name, street directional prefix, street number, street suffix, unit type, and unit number (e.g., '125 Main Street S Unit 5'). |
| location.locality | string | The city portion of the address (e.g., CHICAGO, ATLANTA, DENVER, etc.). |
| location.regionCode | string | The two-letter state code of the address(e.g., CA, NV, WA, etc.). |
| location.postalCode | string | Postal Code portion of the address (e.g., 92675). |
| location.postalCodeExt | string | The four-digit code of the address. Also referred to as the 'plus 4 code' and the 'add on code.' Used by the US Postal Service to identify a geographic segment within a five-digit postal ZIP code (e.g., 5437). |
| location.countryCode | string | ISO 3166 alpha-2 country code (e.g., 'US' for the United States). |
| location.representativePoint.longitude | double | 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.wkt | string | 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. |
| physicalFeatures.height.average | float | Average height of the structure. |
| physicalFeatures.height.max | float | Max height of the structure. |
| physicalFeatures.height.min | float | Min height of the structure. |
| physicalFeatures.groundElevation.average | float | Average ground elevation of the structure. |
| physicalFeatures.groundElevation.max | float | Max ground elevation of the structure. |
| physicalFeatures.groundElevation.min | float | Min ground elevation of the structure. |
| physicalFeatures.area.footPrintArea | float | Structure footprint area. |
| numberOfStories | integer | The number of stories this structure has. |
| propertyClass | string | Property class on which the structure stands. |
| parcelCount | number | The number of parcels that this structure touches. |
| business | boolean | True/False if this building is a business. |
| parcels[].$ref | string | API url that references this related parcel |
| parcels[].id | string | LightBox parcel id that links back to the related parcel |
| parcels[].primaryBuilding | boolean | If true then this structure is the primary structure for this related 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?
.png?sv=2022-11-02&spr=https&st=2024-12-04T08%3A49%3A34Z&se=2024-12-04T09%3A04%3A34Z&sr=c&sp=r&sig=6E9MMUjxSWNkJ%2BGB6eLch1tGV6GZUXaNlkXHUwR627g%3D){kind=logo}