Builder Sites Documentation

Print
Dark
Light
PDF

Builder Sites Documentation

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Purpose

The LightBox Builder Sites API allows the end user to understand residential development that is currently underway in an area. This API tracks the top 350 residential builders in the country. This API includes links back to the builder website and the community website, as well as min and max square area, and low and high purchase price.

Swagger: OAS 3.1 Specification

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 Builder Sites by Geometry

Return builder site records based on a geometry WKT (Well Known Text) string.

Examples:

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 /buildersites/us/geometry?wkt={wkt}

Example requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/buildersites/us/geometry?wkt=POINT(-122.40317865990883 45.585729937697515)

https://api.lightboxre.com/v1/buildersites/us/geometry?wkt=POINT(-122.40317865990883 45.585729937697515)

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

Get Builder Sites by ID

Return builder site records by unique 'ID.'

GET /buildersites/us/{id}

Example requests

curl -X GET -H ‘x-api-key: (api_key)’ https://api.lightboxre.com/v1/buildersites/us/542188230_1053

https://api.lightboxre.com/v1/buildersites/us/542188230_1053

Parameters

Parameter	Type	Description	Usage
id	path	Unique Builder Site ID. This ID is returned within the response.	required

Response

Media type: application/json

Builder Sites Tile Request

Use within common map controls to show builder site points as a tile overlay.

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

Example Requests

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

https://api.lightboxre.com/v1/buildersites/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

Builder Sites Tile Bounding Box Request

Use within common map controls to show builder site points as a bounding box overlay.

GET /buildersites/us/tile

Example Requests

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

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

Parameters

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

Response

Media type: image/png

API Response

For each endpoint other than 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
      }
    }
  },
  "buildersites": [
    {
      "$ref": "string",
      "location": {
        "representativePoint": {
          "longitude": 0,
          "latitude": 0,
          "geometry": {
            "wkt": "string"
          }
        },
        "geometry": {
          "wkt": "string"
        },
        "streetAddress": "string",
        "locality": "string",
        "regionCode": "CA",
        "postalCode": "string",
        "postalCodeExt": "string",
        "countryCode": "US"
      },
      "builderName": "KB Homes",
      "builderUrl": "https://www.kbhome.com",
      "community": "Presidential Meadows",
      "communityUrl": "https://www.kbhome.com/new-homes-austin",
      "propertyType": "string",
      "propertyStatus": "string",
      "minPrice": 0,
      "maxPrice": 0,
      "minSquareArea": 0,
      "maxSquareArea": 0
    }
  ]
}

Field Dictionary

Field	Type	Description
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).
builderName	string	Name of the builder for this site.
builderUrl	string	Builder company URL.
community	string	Community name.
communityUrl	string	URL for this community.
propertyType	string	A list of property type attributes as defined by the builder.
propertyStatus	string	Property status as defined by the builder.
minPrice	float	Minimum property price of the community as stated by the builder.
maxPrice	float	Maximum property price of the community as stated by the builder.
minSquareArea	number	Minimum square area of the products being built.
maxSquareArea	number	Maximum square area of the products bring built.

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

Builder Sites Release Notes

Table of contents

Purpose
API Requests
API Response
Field Dictionary
HTTP Error Codes