Parcels

Retrieves parcel and footprints data based on one or more U.S. location inputs. The data extraction is parcel based, meaning it retrieves data on all the buildings within the parcel at the requested location.

GET https://us-api.geox.ai/v1/parcels

Query Parameters

The request can contain up to 100 locations.

Name	Type	Description
location	string	Required. The location to search for. Can be an address or coordinates.

Input Formats

• Address: Free text format. Ideally: [Street Number] [Street Name], [City], [State/Province] [Postal Code], [Country].
• Coordinates: Lat/Lng format: lat, lng (e.g., 42.937, -71.413).
• Multiple Locations: Append additional locations using the &location= parameter.

---

Response Schema

The response returns a list of locations, each containing a parcel object and an array of footprints.

{
"data": [
  {
    "parcel": { ...Parcel Object },
    "footprints": [{ ...Footprint Object }]
  }
]
}

---

Example Usage

Example Request

cURL

curl --location 'https://us-api.geox.ai/v1/parcels?location=1600+Amphitheatre+Parkway,+Mountain+View,+CA' \
--header 'Authorization: Bearer YOUR_TOKEN'

JavaScript

fetch('https://us-api.geox.ai/v1/parcels?location=1600+Amphitheatre+Parkway,+Mountain+View,+CA', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Python

import requests

url = "https://us-api.geox.ai/v1/parcels"
params = {
    "location": "1600 Amphitheatre Parkway, Mountain View, CA"
}
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Example Response

{
  "data": [
    {
      "parcel": {
        "parcel_id": "3301100116618",
        "pool_count": 0,
        "pool_enclosure_count": 0,
        "temporary_pool_count": 0,
        "trampoline_count": 0,
        "number_of_buildings_in_parcel": 32
      },
      "footprints": [
        {
          "parcel_id": "3301100116618",
          "footprint_id": "33011001166183110000",
          "center_long": -71.41314975284693,
          "center_lat": 42.93783754514559,
          "state": "New Hampshire",
          "county": "Hillsborough",
          "crs": 4326,
          "footprint_area": 2820.45,
          "year_built": null,
          "occupancy": null,
          "occupancy_of_closest_building": null,
          "land_use_description": null,
          "roof_type": "gable",
          "roof_material": "shingle",
          "roof_condition": "fair",
          "tarp_evidence": false,
          "flat_area": 0,
          "hip_area": 678.02,
          "rust_area": 0,
          "ponding_area": 0,
          "discoloration_area": 669.31,
          "solar_panel_area": 0,
          "air_conditioner_count": 0,
          "building_height": null,
          "ground_height_amsl": null,
          "number_of_stories": null,
          "square_footage": null,
          "tree_overhang_percent": 0,
          "distance_to_tree": 48.88,
          "distance_to_shrub": 18.5,
          "distance_to_vegetation": 18.5,
          "tree_zone_1": 0,
          "tree_zone_2": 0,
          "tree_zone_3": 0,
          "tree_zone_4": 2.24,
          "shrub_zone_1": 0,
          "shrub_zone_2": 0.88,
          "shrub_zone_3": 21.54,
          "shrub_zone_4": 40.69,
          "vegetation_zone_1": 0,
          "vegetation_zone_2": 0.88,
          "vegetation_zone_3": 21.54,
          "vegetation_zone_4": 40.91,
          "distance_to_coast": 27.46,
          "distance_to_water_body": 0.51,
          "distance_to_fire_station": 0.95,
          "distance_to_closest_building": 101.21,
          "image_date": "2024-04-25T00:00:00.000Z",
          "model_run_date": "2024-12-08T00:00:00.000Z",
          "geometry": "0103000020E6100000010000000B00000058EBD62B70DA51C0E8F6F4390D7845409FE103AE6FDA51C0A40DCF290978454009DDFE946EDA51C0A17D4E7509784540A4B9D13B6EDA51C026C66A92067845404C17A7E96FDA51C08A5D411B06784540C469FC1B70DA51C0080DB3BE077845407A4488D470DA51C0FB5C5E8C077845406028E6F170DA51C04274B17F087845409C6596D871DA51C0EDF4F844087845402A7FE65F72DA51C080C9C2A90C78454058EBD62B70DA51C0E8F6F4390D784540"
        }
      ]
    }
  ]
}

---

Error Responses

Code	Meaning	Description
400	Bad Request	Missing or malformed address query parameter
401	Unauthorized	Missing or invalid authentication token
404	Not Found	No parcels matched the provided address(es)
429	Too Many Requests	Usage limit exceeded. Includes X-Usage-Left and X-User-Id headers
500	Internal Server Error	Query timeout (over 15 seconds) or unexpected backend error