Skip to main content

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.

This guide walks you through making your first request to the Vangrid Enterprise Spatial API. By the end, you’ll have queried real-time spatial data and seen a live response with ground truth and provenance information.
1

Request access and get your API key

Vangrid is available through an enterprise account. To get started, email hello@vangrid.io with a brief description of your use case and the team or organization you’re building for.Once your account is provisioned, you’ll receive an invitation to the Vangrid dashboard where you can generate and manage API keys.
Store your API key in an environment variable such as VANGRID_API_KEY. Never hard-code credentials in your source code or commit them to version control.
2

Authenticate your requests

Every request to the Vangrid API must include your API key as a Bearer token in the Authorization header.
Authorization: Bearer <your-api-key>
Here’s a minimal authenticated request to confirm your credentials are working:
curl -X GET https://api.vangrid.io/v1/status \
  -H "Authorization: Bearer $VANGRID_API_KEY"
A successful response returns 200 OK. If you receive a 401, double-check that your key is correct and has not expired. See Authentication for details on handling credential errors.
3

Make your first spatial query

The /v1/spatial/query endpoint returns real-time ground truth for a geographic area of interest. You define the area using a GeoJSON polygon and specify the data resolution you need.
curl -X POST https://api.vangrid.io/v1/spatial/query \
  -H "Authorization: Bearer $VANGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi": {
      "type": "Polygon",
      "coordinates": [[
        [-122.4194, 37.7749],
        [-122.4094, 37.7749],
        [-122.4094, 37.7849],
        [-122.4194, 37.7849],
        [-122.4194, 37.7749]
      ]]
    },
    "max_age_seconds": 30
  }'
A successful response looks like this:
{
  "query_id": "q_8f3a2c1d9e4b7a06",
  "timestamp": "2026-05-22T14:03:11.482Z",
  "node_count": 847,
  "ground_truth_score": 0.97,
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-122.4194, 37.7749],
      [-122.4094, 37.7749],
      [-122.4094, 37.7849],
      [-122.4194, 37.7849],
      [-122.4194, 37.7749]
    ]]
  },
  "data_points": [
    {
      "node_id": "node_4a9f2c",
      "lat": 37.7799,
      "lon": -122.4144,
      "observation": "clear",
      "confidence": 0.99,
      "captured_at": "2026-05-22T14:03:10.901Z",
      "provenance_hash": "sha256:a3f8c2d1e94b7605af2e1d8c3b9a4f7e2c6d1a8b"
    }
  ],
  "provenance_hash": "sha256:9e3b1c7f4a2d8605bf1e4d7c2a8f3b9e1c4d7a2f"
}
Key response fields:
  • node_count — Number of edge nodes that contributed data to this query.
  • ground_truth_score — Confidence in the spatial data, from 0 to 1. Scores above 0.9 indicate high-fidelity ground truth.
  • provenance_hash — A cryptographic hash covering the entire response. Use this to verify data integrity.
  • data_points — Individual observations from contributing edge nodes, each with its own confidence score and provenance hash.
4

Stream live spatial data

For applications that need continuous updates — such as tracking moving objects or monitoring dynamic environments — the Vangrid Streaming API delivers ground truth in real time over a persistent connection.
curl -N -X GET \
  "https://api.vangrid.io/v1/spatial/stream?geometry=POLYGON((-122.4194+37.7749,-122.4094+37.7749,-122.4094+37.7849,-122.4194+37.7849,-122.4194+37.7749))" \
  -H "Authorization: Bearer $VANGRID_API_KEY" \
  -H "Accept: text/event-stream"
The stream emits Server-Sent Events (SSE). Each event contains a JSON payload in the same format as the spatial query response above, updated as new observations arrive from edge nodes in your area of interest.
Streaming connections are subject to rate limits based on your account tier. Contact hello@vangrid.io if you need higher throughput for production workloads.

​
Next steps

Now that you’ve made your first request, explore the full API surface:

Authentication

Learn about credential management, auth errors, and security best practices.

API reference

Browse every endpoint, parameter, and response schema in the Enterprise Spatial API.