ATLAS natural language video search | NaviSavi Commercial API

{
  "query": "luxury rooftop hotels in Tokyo",
  "filters": {},
  "data": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "publisher": {
        "@type": "string",
        "name": "string",
        "url": "string"
      },
      "duration": 1.1,
      "thumbnailUrl": "string",
      "clipUrl": "string",
      "thumbnails": {
        "jpeg": "string",
        "png": "string",
        "webp": "string"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  },
  "coordinates": [
    {
      "id": "string",
      "lat": 1.1,
      "lng": 1.1,
      "title": "string",
      "thumbnailUrl": "string"
    }
  ]
}

Search for videos using a natural language query. Pass any descriptive phrase — such as luxury rooftop hotels in Tokyo or sunset beach walks in Greece — and the endpoint returns matching videos. The response includes a filters field showing what was applied, which can be useful for debugging or display.

Requires the videos.atlas_search permission.

For simpler keyword or point-of-interest searches, use the search parameter on GET /v1/videos instead — it requires only the videos.read permission.

Set includeCoordinates=true to also receive a coordinates array of up to 500 map points for the full result set of the query, for rendering a map alongside the results.

Search for videos using a natural language query. Pass any descriptive phrase — such as `luxury rooftop hotels in Tokyo` or `sunset beach walks in Greece` — and the endpoint returns matching videos. The response includes a `filters` field showing what was applied, which can be useful for debugging or display. Requires the `videos.atlas_search` permission. For simpler keyword or point-of-interest searches, use the `search` parameter on `GET /v1/videos` instead — it requires only the `videos.read` permission. Set `includeCoordinates=true` to also receive a `coordinates` array of up to 500 map points for the full result set of the query, for rendering a map alongside the results.

Authentication

x-api-keystring

API key issued with your NaviSavi plan

Query parameters

pageintegerOptional>=1Defaults to 1

Page number (1-based)

limitintegerOptional1-100Defaults to 20

Results per page (max 100)

qstringRequired1-200 characters

Natural language search query (maximum 200 characters)

includeCoordinatesenumOptional

When true, include a coordinates array of up to 500 lightweight map points covering the entire result set of the query (not just the current page), suitable for rendering alongside the results. Off by default.

Allowed values:

thumbnailWidthintegerOptional>=1Defaults to 1280

Thumbnail width in pixels

thumbnailHeightintegerOptional>=1Defaults to 720

Thumbnail height in pixels

thumbnailTimedoubleOptional>=0Defaults to 4

Time offset in seconds for thumbnail frame (clamped to video duration, or 30s if unknown)

thumbnailTypeenumOptionalDefaults to png

Thumbnail image format

Allowed values:

Response

Search results with derived filters

querystring

The original query string

filtersmap from strings to any

Structured filters derived from the query by ATLAS

datalist of objects

metaobject

coordinateslist of objectsOptional

Map points for the entire filtered result set (not just the current page), capped at 500. Present only when includeCoordinates=true. Independent of pagination, so request it once (e.g. on page 1) and reuse it while paging the same query.

Errors

400

Bad Request Error

403

Forbidden Error

500

Internal Server Error