Login
    Contents x
    Location Info Documentation
      • Print
      • Dark
        Light
      • PDF
      Contents

      Location Info Documentation

        • Print
        • Dark
          Light
        • PDF
        Article summary

        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

        ParameterTypeDescriptionUsage
        wktqueryThe geometry of the location expressed in WKT format.required
        bufferDistancequeryBuffer distance expressed in 'bufferUnits.'optional
        bufferUnitqueryThe 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

        ParameterTypeDescriptionUsage
        idpathcensus block geoid or census block group geoidrequired

        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

        ParameterTypeDescriptionUsage
        idpathParcel LightBox ID, e.g., 0201MABNPDBU5D2EGP08YArequired

        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

        ParameterTypeDescriptionUsage
        idpathStructure LightBox ID, e.g., 050151K0AO2OYB14ZNWS7Qrequired

        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

        ParameterTypeDescriptionUsage
        idpathAddress LightBox ID, e.g., 0606ZGPRLD5KGWFYRD7QH9required

        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

        ParameterTypeDescriptionUsage
        idpathAssessment LightBox ID, e.g., 0306F25KSXL0JZ4RTLPP99required

        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

        ParameterTypeDescriptionUsage
        zoompathTile zoom level, which can be a minimum of '13' and a maximum or '21.'required
        xpathTile column.required
        ypathTile 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

        ParameterTypeDescriptionUsage
        bboxqueryA bounding box expressed in the NAD83 projected coordinate system.required
        widthqueryWidth of the result imagerequired
        heightqueryHeight of the result imagerequired

        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

        ParameterTypeDescriptionUsage
        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

        FieldTypeDescription
        $refstringAPI reference back to this object.
        idstringLightBox Location Info ID.
        fipsstringFederal 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.countryCodestringISO 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
        		doubleA 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
        		doubleThe geometry of the location expressed in WKT (well-known text) format.
        location.geometrystringThe geometry of the location expressed in WKT (well-known text) format.
        assessmentLandUsestringThe assessor code describing how the parcel of land is used that the location is located on.
        bslTypestringA description from a list of standardized values indicating which type of broadband-serviceable category the location falls into.
        nonBSLReasonstringA description indicating why a locale is not considered broadband-serviceable.
        unitCount.businessintegerThe number of business units at the location.
        unitCount.residentialintegerThe number of residential units at the location.
        residentialBusinessIndicatorstringA code indicating if the occupancy at the locale is residential or business-based.
        censusBlockstringA 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.
        classificationstringA 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.
        isBSLbooleanA true/false value to determine if the locale is broadband-serviceable or not.
        isPrimaryAddressbooleanA true/false value indicating if the address is a primary address.
        isStructurebooleanA true/false value to determine if the locale is a structure or not.
        locationTypestringA 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.
        locationDescriptionstringDescriptive 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
        202Accepted, no content
        204Successful, 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.
        503Service Unavailable.




        Was this article helpful?
        What's Next
        LightBox
        LightBox Developer
        Data
        Connect With Us
        Contact
        • +1 (800) 624-0470
        Copyright © 2024 LightBox Holdings, L.P All Rights Reserved
        Change password!
        Changing your password will log you out immediately. Use the new password to log back in.
        Change profile
        Success!
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.
        Logout