API Response Commonalities

Introduction

This article will present some of the API response commonalities for all API endpoint responses that you will encounter working with LightBox APIs. 

At the top level of all responses we carry two main pieces of information related to the response, $ref and $metadata.

$ref 

The $ref value will contain the exact API and parameters you used, which will return this result:

{
  "$ref": "https://api.lightboxre.com/parcels/us/0200HK4FSP4RPX8VVBQ1N0",
}

$metadata

The $metadata object provides information about the data being returned in the response.

The objects listed below exist in responses that contain data that represent each object. For example, $metadata.geogcs exists when a geometry feature or latitude and longitude are returned.

{
  "$ref": "string",
  "$metadata": {
    "currency": {
      "code": "USD"
    },
    "geogcs": {
      "epsg": "4326"
    },
    "units": {
      "length": "m",
      "area": "sqm"
    },
    "recordSet": {
      "totalRecords": 1,
      "bbox": {
        "xMax": -105.250409,
        "xMin": -105.251916,
        "yMax": 40.023629,
        "yMin": 40.022576
      }
    }
  }

$metadata.geogcs

$metadata.geogcs provides information for the geometry and the projected reference system that it is in.

{
  "$metadata": {
    "geogcs": {
      "epsg": "4326"
    },
  }

$metadata.currency

$metadata.currency provides the currency for attributes that relate to money, such as price or value.

{
  "$ref": "string",
  "$metadata": {
    "currency": {
      "code": "USD"
    },
}

$metadata.units

$metadata.units provides the units that are used to define attributes such as length and area.

{
  "$metadata": {
    "units": {
      "length": "m",
      "area": "sqm"
    },

$metadata.recordset

$metadata.recordset provides information on the returned result, such as the total records returned and bounding box of the record set.

{
  "$metadata": {
    "recordSet": {
      "totalRecords": 10,
      "bbox": {
        "xMax": -105.250409,
        "xMin": -105.251916,
        "yMax": 40.023629,
        "yMin": 40.022576
      }
    }
  }

$metadata.geocode

$metadata.geocode is only returned when the resource has a locate by address. In this case, you will be provided confidence information on how well the address that was entered matches the address that it is matched to in our data.

{	
	"$metadata": {
		"geocode": {
			"confidence": {
			"streetNumber": 1,
			"streetName": 1,
			"locality": 0.9090909090909091,
			"postalCode": 0,
			"score": 0.979
		},
		"precisionCode": 10
		}
	},
}

Plurality 

We use plurality to determine the type of object you will receive. If the resource within the URL is plural, you will always receive an array result even if a single record is returned. If the resource is singular, then you will receive a single object.