Quickstart: location and video stream

An entity becomes useful when it has a position and a feed. This page attaches both to the camera from Quickstart: create your first entity, and ends with a playable stream URL.

Before you start: a token, your organization_id, and the entity_id from the previous page.

1. Attach a location.

   POST /v3/entities/{entityId}/locations. Two fields are required: a GeoJSON position and a source string naming what produced the fix. Coordinates are longitude first (GeoJSON order); crs: "EPSG:4326" says you are sending plain longitude/latitude rather than the default Earth-centered coordinates.

   curl

   curl -s -X POST "https://api.usg.legion.picogrid.com/v3/entities/$ENTITY_ID/locations" \
     -H "Authorization: Bearer $TOKEN" -H "X-ORG-ID: $ORG_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "position": { "type": "Point", "coordinates": [-118.3935, 33.9258] },
       "crs": "EPSG:4326",
       "source": "quickstart",
       "recorded_at": "2026-08-13T18:45:00Z"
     }'

   Python

   requests.post(
       f"{API}/v3/entities/{entity_id}/locations",
       headers={"Authorization": f"Bearer {token}", "X-ORG-ID": org_id},
       json={
           "position": {"type": "Point", "coordinates": [-118.3935, 33.9258]},
           "crs": "EPSG:4326",
           "source": "quickstart",
           "recorded_at": "2026-08-13T18:45:00Z",
       },
       timeout=30,
   ).raise_for_status()

   Locations are a history, not a single value: every POST appends a fix, and the map shows the newest. GET /v3/entities/$ENTITY_ID/locations returns the trail, newest first — your point coming back is the verify step, and the entity now renders on the Orion map at those coordinates.

2. Register a video stream.

   POST /v3/video declares a stream for the entity: who it belongs to, a stream name, and the protocol you will publish with.

   curl

   curl -s -X POST "https://api.usg.legion.picogrid.com/v3/video" \
     -H "Authorization: Bearer $TOKEN" -H "X-ORG-ID: $ORG_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "entity_id": "'$ENTITY_ID'",
       "stream_name": "walkthrough-cam",
       "protocol": "rtsp",
       "metadata": { "resolution": "1920x1080", "frame_rate": 30 }
     }'

   Python

   resp = requests.post(
       f"{API}/v3/video",
       headers={"Authorization": f"Bearer {token}", "X-ORG-ID": org_id},
       json={
           "entity_id": entity_id,
           "stream_name": "walkthrough-cam",
           "protocol": "rtsp",
           "metadata": {"resolution": "1920x1080", "frame_rate": 30},
       },
       timeout=30,
   )
   resp.raise_for_status()
   stream = resp.json()
   print(stream["publish_url"])
   print(stream["playback_url"])

   The response contains the two URLs that matter:

   {
     "entity_id": "7f3d2a10-5b6c-4e8f-9a01-23d4e5f6a7b8",
     "stream_name": "walkthrough-cam",
     "protocol": "rtsp",
     "is_active": false,
     "publish_url": "rtsps://api.usg.legion.picogrid.com:8322/<org_id>/<entity_id>/walkthrough-cam",
     "playback_url": "https://api.usg.legion.picogrid.com/v3/media/hls/<org_id>/<entity_id>/walkthrough-cam/index.m3u8"
   }

   publish_url is where your camera or encoder sends video (TLS-wrapped RTSP, authenticated). playback_url is where anyone in the org watches (HLS). is_active stays false until a publisher actually connects.

3. Publish and watch.

   Point any RTSP source at the publish URL — a real camera, or ffmpeg as a stand-in:

   ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 \
     -c:v libx264 -preset veryfast -f rtsp "$PUBLISH_URL"

   Then open the playback_url in VLC, or query POST /v3/video/search and see your stream with is_active: true. That is the full loop: an entity, on the map, with live video attached — the same three objects every fielded unit maintains automatically.

Protocols

rtsp, rtmp, hls, webrtc, and srt are accepted at registration. RTSP is the common choice for cameras; whichever you declare, playback for consumers is HLS at the playback_url.

Troubleshooting

Response	Cause	Fix
400 on location	Missing position or source	Both are required; position is GeoJSON {type, coordinates}.
Point renders in the wrong place	Coordinates reversed	GeoJSON is [longitude, latitude], not lat/lon.
Stream stays is_active: false	Nothing has connected to publish_url	Start the publisher; check it can reach port 8322.
409 on stream create	stream_name already exists for this entity	Names are unique per entity; pick another or delete the old one.

Next steps

• Video Streams API reference — recordings, DVR search, and segment download live under the same group.
• Entity Locations reference — batch search across all entities with POST /v3/entities/locations/search.