API Reference

Sites

7 endpoints

Overview

Sites represent physical locations where aerial data is collected. Each site belongs to an account and includes address information, geographic coordinates, and boundary geometry. Campaigns are associated with sites — a site must have a valid boundary geometry before it can be used in a campaign.

Site geometry is sent and returned as GeoJSON. The geometry API is available to client users only. You may read geometries on sites you own or sites shared with you, but you can only create or update geometries on sites your account owns.

GET /api/v1/sites Requires Auth

List all sites for your account and shared sites you can access.

Parameters

Name In Type Required Description
page query integer No Page number (default: 1)
per_page query integer No Items per page (default: 25, max: 100)

cURL Example

cURL
curl "https://app.raad.com/api/v1/sites?page=1&per_page=25" \
  -H "Authorization: Bearer <JWT_TOKEN>"

Responses

200 Sites list
Response
{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "type": "site",
      "attributes": {
        "name": "Solar Farm Alpha",
        "description": "200-acre solar installation",
        "address1": "1234 Solar Drive",
        "address2": null,
        "city": "Austin",
        "state": "TX",
        "zipCode": "78701",
        "country": "US",
        "siteType": "Commercial - Solar",
        "latitude": 30.2672,
        "longitude": -97.7431,
        "fullAddress": "1234 Solar Drive, Austin, TX 78701",
        "area": 0.81,
        "geometry": {
          "type": "Polygon",
          "coordinates": [[
            [-97.744, 30.268], [-97.742, 30.268],
            [-97.742, 30.266], [-97.744, 30.266],
            [-97.744, 30.268]
          ]]
        },
        "status": "active",
        "faaRestrictionsSummary": "No restrictions",
        "createdAt": "2024-01-05T09:00:00.000Z",
        "updatedAt": "2024-02-20T16:45:00.000Z"
      }
    }
  ]
}

POST /api/v1/sites Requires Auth

Create a new site with an optional GeoJSON boundary. Geometry is validated to be between 500 sq ft and 100 sq km.

Request Body

Name Type Required Description
name string Yes Site name
description string No Site description
address_1 string Conditional Street address (required if no geometry)
city string Conditional City (required if no geometry)
state string Conditional State / province
zip_code string No Postal code
country string No Country code
site_type string No Site type classification
geometry GeoJSON No Boundary polygon as GeoJSON

cURL Example

cURL
curl -X POST https://app.raad.com/api/v1/sites \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "name": "Solar Farm Alpha",
    "description": "200-acre solar installation",
    "address_1": "1234 Solar Drive",
    "city": "Austin",
    "state": "TX",
    "zip_code": "78701",
    "site_type": "Commercial - Solar",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[
        [-97.744, 30.268], [-97.742, 30.268],
        [-97.742, 30.266], [-97.744, 30.266],
        [-97.744, 30.268]
      ]]
    }
  }'

Responses

201 Site created
422 Validation failed (invalid GeoJSON, geometry too small/large, missing address)
Error: Geometry Too Small
{
  "error": "Validation failed",
  "messages": ["Boundary is too small (minimum 500 sq ft / ~46 sq m)"]
}

GET /api/v1/sites/{site_id}/geometries Requires Auth

List all geometries belonging to an accessible site.

Parameters

Name In Type Required Description
site_id path uuid Yes Site UUID
page query integer No Page number (default: 1)
per_page query integer No Items per page (default: 100, max: 100)
system_type query string No Filter by system type, e.g. building_structure
geometry_type query string No Filter by geometry type: point, linestring, polygon, or multipolygon

cURL Example

cURL
curl "https://app.raad.com/api/v1/sites/<SITE_ID>/geometries?page=1&per_page=100" \
  -H "Authorization: Bearer <JWT_TOKEN>"

Responses

200 Geometries list
Response
{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "type": "site_geometry",
      "attributes": {
        "label": "Building A",
        "description": null,
        "geometryType": "point",
        "systemType": "building_structure",
        "latitude": 33.7425,
        "longitude": -118.4081,
        "locked": false,
        "geometry": { "type": "Point", "coordinates": [-118.4081, 33.7425] },
        "properties": null,
        "createdAt": "2024-01-05T09:00:00.000Z",
        "updatedAt": "2024-01-05T09:00:00.000Z"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 100,
      "total": 1,
      "total_pages": 1
    },
    "system_types": {
      "building_structure": "Building Structure",
      "grid_power": "Grid Power",
      "on_site_power": "On-site Power",
      "backup_power": "Backup Power",
      "cooling": "Cooling",
      "parking_lot": "Parking Lot",
      "construction": "Construction",
      "solar_array_centerline": "Solar Array Centerline",
      "linear_asset": "Linear Asset",
      "capture_area": "Capture Area"
    }
  },
  "links": {
    "next": null
  }
}
404 Site not found or not accessible
422 Unknown system_type or geometry_type

POST /api/v1/sites/{site_id}/geometries Requires Auth

Create a geometry on a site your account owns. Pass a GeoJSON Point, LineString, Polygon, or MultiPolygon in geojson, or pass latitude and longitude to create a Point. The same geometry cannot be added twice to the same site. Shared sites are read-only.

Request Body

Name Type Required Description
latitude number Conditional WGS84 latitude (required if geojson is omitted)
longitude number Conditional WGS84 longitude (required if geojson is omitted)
geojson GeoJSON Conditional Point, LineString, Polygon, or MultiPolygon
label string No Geometry label
description string No Geometry description
system_type string No Controlled value from system_types meta
properties object No Arbitrary JSON metadata (max 50 keys, 1 MiB)

cURL Examples

cURL: lat/lon (Point)
curl -X POST https://app.raad.com/api/v1/sites/<SITE_ID>/geometries \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "latitude": 33.9425,
    "longitude": -118.4081,
    "label": "Building A",
    "system_type": "building_structure"
  }'
cURL: GeoJSON Polygon
curl -X POST https://app.raad.com/api/v1/sites/<SITE_ID>/geometries \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "geojson": {
      "type": "Polygon",
      "coordinates": [[
        [-118.32, 33.74], [-118.31, 33.74],
        [-118.31, 33.75], [-118.32, 33.75],
        [-118.32, 33.74]
      ]]
    },
    "label": "Building outline",
    "system_type": "building_structure"
  }'

Responses

201 Geometry created. The response includes a Location header.
403 Shared sites are read-only
422 Missing coordinates, invalid GeoJSON, duplicate geometry, or invalid system_type

Note: GeoJSON Polygon inputs are stored internally as MultiPolygon and returned that way by default from read endpoints. The geometry_type field still reports polygon.

GET /api/v1/sites/{site_id}/geometries/{id} Requires Auth

Retrieve a single geometry from an accessible site.

Parameters

Name In Type Required Description
site_id path uuid Yes Site UUID
id path uuid Yes Geometry UUID

cURL Example

cURL
curl https://app.raad.com/api/v1/sites/<SITE_ID>/geometries/<GEOMETRY_ID> \
  -H "Authorization: Bearer <JWT_TOKEN>"

Responses

200 Geometry found
404 Geometry or site not found

PATCH /api/v1/sites/{site_id}/geometries/{id} Requires Auth

Update metadata or replace the geometry of an owned site geometry. Locked geometries reject changes to shape or system_type; labels and descriptions may still be edited.

Request Body

Same fields as create. Only include the fields you want to change. To replace the shape, include geojson; to replace a Point with another Point, include latitude and longitude.

cURL Example

cURL
curl -X PATCH https://app.raad.com/api/v1/sites/<SITE_ID>/geometries/<GEOMETRY_ID> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{"label": "Renamed building", "description": "Updated description"}'

Responses

200 Geometry updated
403 Shared sites are read-only
409 Geometry is locked; shape or system_type cannot change
422 Invalid GeoJSON, duplicate geometry, or invalid parameter

GET /api/v1/sites/{id} Requires Auth

Retrieve a single site with relationships.

Parameters

Name In Type Required Description
id path uuid Yes Site UUID

cURL Example

cURL
curl https://app.raad.com/api/v1/sites/<SITE_ID> \
  -H "Authorization: Bearer <JWT_TOKEN>"

Responses

200 Site found
Response
{
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "type": "site",
    "attributes": { ... },
    "relationships": {
      "account": { "data": { "id": "...", "type": "account" } },
      "campaigns": { "data": [{ "id": "...", "type": "campaign" }] }
    }
  }
}
404 Site not found

Geometry Validation

Site boundaries and geometries must be valid GeoJSON. The API enforces the following geometry constraints:

  • Allowed types: Point, LineString, Polygon, MultiPolygon
  • Coordinates: finite [longitude, latitude] pairs in WGS 84 ranges
  • Polygon rings: at least four positions, closed (first == last)
  • Maximum vertices: 10,000 positions per geometry
  • Properties: object with at most 50 keys, total size under 1 MiB
  • GeoJSON size: must be under 1 MiB

If validation fails, the API returns a 422 with a descriptive error message. Coordinates must be in WGS 84 (EPSG:4326) — standard longitude/latitude pairs.

Site Object

The Site object contains the following attributes:

Attribute Type Description
id uuid Unique identifier
name string Site name
description string Site description
address1 string Street address line 1
address2 string Street address line 2
city string City
state string State or province
zipCode string Postal code
country string Country code
siteType string Site type classification
latitude decimal Site center latitude
longitude decimal Site center longitude
fullAddress string Formatted full address
area decimal Boundary area in km²
geometry GeoJSON Boundary polygon as GeoJSON (null if not set)
status string Current status
faaRestrictionsSummary string FAA airspace summary
createdAt datetime ISO 8601 creation timestamp
updatedAt datetime ISO 8601 last updated