Stream API
Endpoint, parameters, request and response.
Overview
Run a complete search in one call. Results come back in the same response; no follow-up request is needed.
Endpoint
POSThttps://api.outerview.ai/v1/stream
Call it from your server with a Bearer API key. Send and receive JSON.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Natural-language description of what to find |
position | object | No | { "points": [{ "latitude", "longitude" }, ...] }. Set one or more points to narrow discovery to the areas around them |
year | number | No | Restrict captures to one calendar year |
interactive | boolean | No | true returns only interactive (360°) results |
limit | number | No | Maximum results returned, capped by your plan. Requests above the cap return 400 |
region_id | string | No | Numeric region ID for a precise geographic scope |
For larger result sets, narrow with position, region_id, or year and issue separate calls. Plan caps are in Limits and Errors.
Request
Real request that produced the response below — a scoped search for potholes in New York.
JSON
{
"query": "potholes in New York",
"position": {
"points": [
{
"latitude": 40.7128,
"longitude": -74.006
},
{
"latitude": 40.7306,
"longitude": -73.9866
}
]
},
"limit": 5
}bash
curl https://api.outerview.ai/v1/stream \
-X POST \
-H "Authorization: Bearer $OUTERVIEW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"potholes in New York","position":{"points":[{"latitude":40.7128,"longitude":-74.006},{"latitude":40.7306,"longitude":-73.9866}]},"limit":5}'Response
Real five-result response for the request above. Only media URLs are redacted. Field definitions are in the Quickstart.
JSON
{
"isSuccess": true,
"result_id": "ac4adb36-4a58-4589-a8f9-f3789a0d0946",
"data": {
"query": "potholes in New York",
"duration_ms": 1183,
"geojson": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": "1928656524330738",
"geometry": {
"type": "Point",
"coordinates": [
-73.959623,
40.801995
]
},
"properties": {
"id": "1928656524330738",
"address": "256 MANHATTAN AVE, New York, NY, 10026, United States",
"duration": 0,
"is_video": false,
"month": "2",
"owner": "iragersh",
"video_id": "3HnfqDwu7WQBM29FRrhyg0",
"source": "mapillary",
"video_url": "<video URL>",
"year": "2025",
"feature_name": "Pothole",
"image_url": "<image URL>",
"interactive": false,
"date": "2025-02-08 17:11:24+00"
}
},
{
"type": "Feature",
"id": "2338893119587774",
"geometry": {
"type": "Point",
"coordinates": [
-73.874708333333,
40.887703333333
]
},
"properties": {
"id": "2338893119587774",
"address": "New York City, New York, United States",
"month": "9",
"source": "mapillary",
"year": "2016",
"feature_name": "Pothole",
"image_url": "<image URL>",
"interactive": false,
"date": "2016-09-06 12:32:00.649+00"
}
},
{
"type": "Feature",
"id": "755424196947069",
"geometry": {
"type": "Point",
"coordinates": [
-73.893147,
40.814596
]
},
"properties": {
"id": "755424196947069",
"address": "1129 LONGWOOD AVE, New York, NY, 10474, United States",
"month": "7",
"owner": "iragersh",
"source": "mapillary",
"year": "2025",
"feature_name": "Pothole",
"image_url": "<image URL>",
"interactive": false,
"date": "2025-07-30 18:46:50+00"
}
},
{
"type": "Feature",
"id": "299783558272838",
"geometry": {
"type": "Point",
"coordinates": [
-73.658178910979,
40.663072744807
]
},
"properties": {
"id": "299783558272838",
"address": "125 Ocean Avenue, Unit 27, Lynbrook, NY, 11563, United States",
"duration": 28,
"is_video": false,
"month": "4",
"owner": "daalso",
"video_id": "a8AJT7L-S8aCV7HTK1LhCw",
"source": "mapillary",
"video_url": "<video URL>",
"year": "2019",
"feature_name": "Pothole",
"image_url": "<image URL>",
"interactive": false,
"date": "2019-04-30 15:33:10.731+00"
}
},
{
"type": "Feature",
"id": "2631119517192915",
"geometry": {
"type": "Point",
"coordinates": [
-74.682877873889,
44.828358571944
]
},
"properties": {
"id": "2631119517192915",
"address": "1461 County Route 55, Brasher Falls, Brasher, NY, 13613, United States",
"duration": 152,
"is_video": false,
"month": "5",
"owner": "hshearer",
"video_id": "mx0p6dvu0vcammy8h8lryr",
"source": "mapillary",
"video_url": "<video URL>",
"year": "2019",
"feature_name": "Pothole",
"image_url": "<image URL>",
"interactive": false,
"date": "2019-05-30 09:09:47+00"
}
}
]
},
"regions": [
{
"id": "4915",
"name": "New York",
"layer": "state",
"state_name": "New York",
"country_name": "United States"
}
],
"year": null
}
}Interactive results carry interactive: true; their video_url is a 360° equirectangular video that the Interactive SDK can play.
On failure the response is { "isSuccess": false, "error": "...", "status": <code> }. See Limits and Errors.