> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vangrid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vangrid Enterprise Spatial API: Overview and Reference

> The Vangrid Enterprise Spatial API provides access to real-time ground truth, spatial queries, data ingestion, and live streaming from the edge network.

The Vangrid Enterprise Spatial API is a REST API that exposes the full power of the Vangrid edge network to your applications. Use it to query real-time spatial observations for any area of interest, ingest data from your own sensors, and subscribe to live ground truth streams.

## Base URL

All API requests are made to:

```
https://api.vangrid.io/v1
```

## Authentication

Every request requires a Bearer token in the `Authorization` header:

```
Authorization: Bearer your-api-key
```

See [API Authentication](/api/authentication) for details on obtaining and managing your API key.

## Request and response format

All request bodies and responses use JSON. Set `Content-Type: application/json` on requests with a body.

Successful responses return HTTP `200` with a JSON body. Errors return the appropriate HTTP status code and a JSON error object:

```json theme={null}
{
  "error": "error_code",
  "message": "Human-readable description of the error."
}
```

## Rate limits

Rate limits depend on your plan tier. The current limit is included in every response via headers:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per minute              |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

When you exceed your rate limit, the API returns `429 Too Many Requests`.

## Endpoints

<CardGroup cols={2}>
  <Card title="Spatial Queries" icon="magnifying-glass-location" href="/api/spatial-queries">
    Query ground truth observations for a geographic area of interest.
  </Card>

  <Card title="Data Ingestion" icon="arrow-up-to-line" href="/api/data-ingestion">
    Submit observations from your own sensors into the Vangrid network.
  </Card>

  <Card title="Streaming" icon="wave-pulse" href="/api/streaming">
    Subscribe to real-time ground truth updates for a defined zone.
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Manage API keys and understand authentication requirements.
  </Card>
</CardGroup>

## Common error codes

| Code                    | HTTP status | Meaning                                   |
| ----------------------- | ----------- | ----------------------------------------- |
| `unauthorized`          | 401         | Missing or invalid API key                |
| `region_not_authorized` | 403         | AOI outside your authorized regions       |
| `invalid_geometry`      | 400         | Malformed GeoJSON in request              |
| `aoi_too_large`         | 400         | Area of interest exceeds maximum size     |
| `rate_limit_exceeded`   | 429         | Too many requests                         |
| `internal_error`        | 500         | Unexpected server error — contact support |

<Note>
  To request access or upgrade your plan, contact [hello@vangrid.io](mailto:hello@vangrid.io).
</Note>