Footprints (V2)

Retrieves footprints data based on batches of U.S. location inputs. The data extraction is footprint based, meaning it retrieves data on a specific requested building.

POST https://us-api.geox.ai/v2/footprints

Request Overview

• Batch Support: Process up to 500 locations in a single batch.
• Tracking: For each requested location, you can provide an input_id for tracking results. This field can be left empty if not needed.
• Geocoding Confidence: V2 provides a geocoding_confidence score per building (typically 0.79-0.99).

Request Body

Name	Type	Description
locations	array[Location]	Required. List of up to 500 location objects.

Location Object

Field	Type	Description
input_id	string	Optional tracking ID for the location.
address	string	Address in free text format.
coordinates	object	Lat/Lng object: {"lat": float, "lng": float}.

---

Response Schema

The response includes batch processing metadata and a list of results. Each result item contains tracking information and the combined footprint/parcel data object.

{
"meta": { ...Meta Object },
"data": [
  {
    "input_id": "string",
    "parcel_id": "string",
    "confidence": float,
    "footprint": { ...Footprint Object }
  }
]
}

---

Example Usage

Example Request

cURL

curl -X POST "https://us-api.geox.ai/v2/footprints" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "locations": [
         {
           "input_id": "req_1",
           "address": "1600 Amphitheatre Parkway, Mountain View, CA"
         }
       ]
     }'

JavaScript

fetch('https://us-api.geox.ai/v2/footprints', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    locations: [
      { input_id: 'req_1', address: '1600 Amphitheatre Parkway, Mountain View, CA' }
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data));

Python

import requests

url = "https://us-api.geox.ai/v2/footprints"
payload = {
    "locations": [
        {"input_id": "req_1", "address": "1600 Amphitheatre Parkway, Mountain View, CA"}
    ]
}
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Example Response

{
  "data": [
    {
      "input_id": "1",
      "parcel_id": "3300300021307",
      "confidence": 0.99,
      "footprint": {
        "footprint_id": "33003000213071380000",
        "center_long": -71.11866172659494,
        "center_lat": 43.97804211973135,
        "state": "New Hampshire",
        "county": "Carroll",
        "crs": 4326,
        "footprint_area": 3809.29,
        "occupancy": "Cell phone accessory store",
        "land_use_description": "commercial",
        "roof_type": "gable",
        "roof_material": "metal",
        "roof_condition": "fair",
        "tarp_evidence": false,
        "flat_area": 1645.9,
        "hip_area": 446.38,
        "building_height": 39.07,
        "number_of_stories": 4,
        "square_footage": 15237.16,
        "tree_overhang_percent": 0,
        "distance_to_tree": 6.46,
        "image_date": "2024-06-25T00:00:00.000Z",
        "model_run_date": "2024-12-08T00:00:00.000Z",
        "pool_count": 0,
        "pool_enclosure_count": 0,
        "temporary_pool_count": 0,
        "trampoline_count": 0,
        "geometry": "0103000020E6100000010000001100000079F517A197C751C05D2B6FE330FD4540BFBD9EBB97C751C042CAB6B731FD45407FAAF69495C751C038073E4632FD4540AD51624595C751C0AC2467C92FFD454024CDB5CE96C751C04DCC98632FFD454032F503D496C751C04C880D8E2FFD45402A88AEE796C751C0476AF6882FFD45400A804DDB96C751C08208E6252FFD45408339483C9BC751C09C4FC0032EFD454030D2B67D9BC751C09710600F30FD4540CF3C37259BC751C04517482630FD4540B3EC9A1A9BC751C0BCA05ED12FFD4540C8339BDF9AC751C0A9FAA3E02FFD4540B6DCCB399BC751C0804A64B232FD4540C278CF3A98C751C0D9C5E97833FD4540E0F7ECE597C751C00D439ED130FD454079F517A197C751C05D2B6FE330FD4540"
      }
    }
  ],
  "meta": {
    "summary": {
      "ok": 6,
      "failed": 0
    }
  }
}