> ## 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.

# Quickstart: Make Your First Vangrid API Call

> Learn how to authenticate, query real-time spatial ground truth, and stream live data from the Vangrid Enterprise Spatial API in minutes.

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.

<Note>
  All endpoint URLs, request examples, and sample responses on this page are illustrative. The Vangrid API is not yet publicly available — [contact us](mailto:hello@vangrid.io) to join early access.
</Note>

<Steps>
  <Step title="Request access and get your API key">
    Vangrid is available through an enterprise account. To get started, email [hello@vangrid.io](mailto: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.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Authenticate your requests">
    Every request to the Vangrid API must include your API key as a Bearer token in the `Authorization` header.

    ```bash theme={null}
    Authorization: Bearer <your-api-key>
    ```

    Here's a minimal authenticated request to confirm your credentials are working:

    <CodeGroup>
      ```bash curl theme={null}
      curl -X GET https://api.vangrid.io/v1/status \
        -H "Authorization: Bearer $VANGRID_API_KEY"
      ```

      ```python python theme={null}
      import os
      import requests

      api_key = os.environ["VANGRID_API_KEY"]

      response = requests.get(
          "https://api.vangrid.io/v1/status",
          headers={"Authorization": f"Bearer {api_key}"},
      )
      print(response.json())
      ```
    </CodeGroup>

    A successful response returns `200 OK`. If you receive a `401`, double-check that your key is correct and has not expired. See [Authentication](/authentication) for details on handling credential errors.
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash curl theme={null}
      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
        }'
      ```

      ```python python theme={null}
      import os
      import requests

      api_key = os.environ["VANGRID_API_KEY"]

      payload = {
          "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,
      }

      response = requests.post(
          "https://api.vangrid.io/v1/spatial/query",
          headers={
              "Authorization": f"Bearer {api_key}",
              "Content-Type": "application/json",
          },
          json=payload,
      )
      print(response.json())
      ```
    </CodeGroup>

    A successful response looks like this:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash curl theme={null}
      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"
      ```

      ```python python theme={null}
      import os
      import requests

      api_key = os.environ["VANGRID_API_KEY"]

      params = {
          "geometry": "POLYGON((-122.4194 37.7749,-122.4094 37.7749,-122.4094 37.7849,-122.4194 37.7849,-122.4194 37.7749))"
      }

      with requests.get(
          "https://api.vangrid.io/v1/spatial/stream",
          headers={
              "Authorization": f"Bearer {api_key}",
              "Accept": "text/event-stream",
          },
          params=params,
          stream=True,
      ) as response:
          for line in response.iter_lines():
              if line:
                  print(line.decode("utf-8"))
      ```
    </CodeGroup>

    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.

    <Note>
      Streaming connections are subject to rate limits based on your account tier. Contact [hello@vangrid.io](mailto:hello@vangrid.io) if you need higher throughput for production workloads.
    </Note>
  </Step>
</Steps>

## Next steps

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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn about credential management, auth errors, and security best practices.
  </Card>

  <Card title="API reference" icon="code" href="/api/overview">
    Browse every endpoint, parameter, and response schema in the Enterprise Spatial API.
  </Card>
</CardGroup>