Logo

Outerview

AboutDocsBeaconDevelopersAPI KeyPlayground
IntroductionQuickstartAuthenticationStream APILimits & ErrorsSDKCLIMCP

Quickstart

From zero to your first results in a few minutes.

1. Get an API key

Create a key in the developer console, then export it:

bash
export OUTERVIEW_API_KEY="ov_your_key"

2. Make your first call

query is the only required field. Describe what you want to find in plain language.

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"}'

3. Optional filters

position limits results to one or more locations. Our model narrows discovery to the areas around the positions you provide.

›curl with position
bash
curl https://api.outerview.ai/v1/stream \
  -X POST \
  -H "Authorization: Bearer $OUTERVIEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "potholes",
    "position": {
      "points": [
        { "latitude": 40.7128, "longitude": -74.0060 },
        { "latitude": 40.7306, "longitude": -73.9866 }
      ]
    }
  }'

year limits results to captures from one calendar year.

›curl with year
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", "year": 2026}'

Use both together to narrow by place and time.

4. Response

This is a real five-result response for potholes in New York. Only media URLs are redacted.

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
  }
}

5. What the fields mean

FieldTypeMeaning
isSuccessbooleanWhether the request completed successfully.
result_idstringIdentifier for this search execution.
data.querystringNatural-language search that was evaluated.
data.duration_msnumberServer processing time in milliseconds.
data.geojsonFeatureCollectionMap-ready matched observations.
features[].id / properties.idstringStable observation identifier.
geometry.typestringGeoJSON geometry type, typically Point.
geometry.coordinates[longitude, latitude]WGS84 map coordinates.
addressstring | nullBest available human-readable location.
datestring | nullCapture timestamp.
year / monthstring | nullCapture year and month when supplied.
sourcestring | nullOrigin of the observation.
ownerstring | nullSource account or contributor when available.
feature_namestringArtifact matched by the search.
image_urlstring | nullStatic image URL; redacted in this example.
is_videoboolean | nullWhether the capture is video.
video_idstring | nullIdentifier for the capture video.
video_urlstring | nullVideo media URL; redacted in this example.
durationnumber | nullVideo duration in seconds.
interactivebooleanWhether the result opens as 360-degree media.
regionsarrayResolved search geography.
yearstring | nullRequested year filter, or null when unrestricted.

The response also reports regions (the geography the search resolved to) and year (the year filter you requested, or null).

Next steps

Full parameter reference: Stream API

Plans and rate limits: Limits and Errors

Render 360° results: SDK