Nexar VirtualCam API

openapi: 3.2.0
info:
  title: CityStream™ VirtualCam VirtualCam API
  description: The CityStream™ VirtualCam API provides a fresh collection of anonymized frames captured by Nexar's network of cameras on the road.
  contact:
    name: Nexar
    url: https://getnexar.com/
    email: api-support@getnexar.com
  license:
    name: 'License: Proprietary'
  version: '4.0'
servers:
- url: https://external.getnexar.com
security:
- Bearer: []
tags:
- name: VirtualCam API
paths:
  /api/virtualcam/v5/frames:
    post:
      tags:
      - VirtualCam API
      description: 'Get anonymized frames for a given area defined by a bounding box or H3 IDs.


        Additional options for filtering and sorting are provided to enhance the precision of the requests.'
      operationId: VcamService_FindRawFrames
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindRawFramesApiRequestParams'
            example:
              bounding_box:
                south_west:
                  longitude: -73.99708049121774
                  latitude: 40.72176834293103
                north_east:
                  longitude: -73.98168795029027
                  latitude: 40.73122344104337
              filters:
                frames_per_h3: 1
                min_frame_quality: 0.7
                road_types:
                - MOTORWAY
                - RESIDENTIAL
                frames_context:
                - DAYLIGHT
                - NIGHTTIME
                start_time: '1688169600000'
                end_time: '1689206400000'
                directions:
                - NORTH
                - NORTH_WEST
              sort_by: QUALITY
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindRawFramesApiResponse'
              example:
                frames:
                - frame_id: 56f8d643be2ff1e674598eccfae2b3e2
                  frame_url: https://external-api.getnexar.com/aod/full/ride/cc07d59669bfa317a4136a7d93965b04/fod_709F23AE-6F53-49E8-A473-98FEB7DBE973.jpg
                  thumbnail_url: https://external-api.getnexar.com/aod/thumbnail/ride/cc07d59669bfa317a4136a7d93965b04/fod_709F23AE-6F53-49E8-A473-98FEB7DBE973.jpg
                  captured_at: '1689242521198'
                  timezone_offset: -14400
                  h3_index_res12: '631243922682792959'
                  gps_info:
                    longitude: -73.985751
                    latitude: 40.733587
                  direction: NORTH_WEST
                  camera_heading: 298.8096008300781
                  frame_quality: 0.9148776531219482
                  frame_context: NIGHTTIME
                  osm_info:
                    osm_node_id_from: '8310246171'
                    osm_node_id_to: '3985008876'
                    road_type: RESIDENTIAL
                frames_fetched: 1
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/nexarBadRequest'
              example:
                status: 400
                error: Bad Request
        '403':
          description: Returned when the user does not have permission to access the resource.
          content:
            application/json:
              schema:
                type: object
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                type: string
                format: string
              example: string
        '500':
          description: This is usually a temporary error due to high server load or a brief endpoint error.
          content:
            application/json:
              schema:
                type: object
      security:
      - Bearer: []
      x-codegen-request-body-name: payload
      summary: Vcam service find raw frames
      x-summary-source: derived
  /api/virtualcam/v4/coverage:
    post:
      tags:
      - VirtualCam API
      description: Get H3 coverage information for a given area defined by a bounding box or H3 IDs.
      operationId: VcamService_GetH3Coverage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetH3CoverageRequestParams'
            example:
              h3_coverage_bounding_box:
                bounding_box:
                  south_west:
                    longitude: -118.25408935546875
                    latitude: 34.05493499798558
                  north_east:
                    longitude: -118.2513427734375
                    latitude: 34.05721051351028
                h3_resolution: 5
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetH3CoverageResponse'
              example:
                coverage:
                - h3_id: '599711151885910015'
                  frame_count: '2494'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/nexarBadRequest'
              example:
                status: 400
                error: Bad Request
        '403':
          description: Access forbidden. Also returned when the requested area is not authorized.
          content:
            application/json:
              schema:
                type: string
                format: string
              example: string
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                type: string
                format: string
              example: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
              example: {}
      security:
      - Bearer: []
      x-codegen-request-body-name: payload
      summary: Vcam service get H3 coverage
      x-summary-source: derived
  /api/virtualcam/v4/frames:
    post:
      tags:
      - VirtualCam API
      description: 'Get anonymized frames for a given area defined by a bounding box or H3 IDs .


        Additional options for filtering and sorting are provided to enhance the precision of the requests.'
      operationId: RoadItemService_FindRawFrames
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apiFindRawFramesApiRequestParams'
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiFindRawFramesApiResult'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/nexarBadRequest'
        '403':
          description: Access forbiden. Also returned when the requested area is not authorized.
          content:
            application/json:
              schema:
                type: string
                format: string
        '429':
          description: API rate limit exceeded.
          content:
            application/json:
              schema:
                type: string
                format: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
      summary: Road item service find raw frames
      x-summary-source: derived
components:
  schemas:
    GetH3CoverageRequestParams:
      title: H3 Coverage Request
      type: object
      properties:
        h3_coverage_bounding_box:
          $ref: '#/components/schemas/H3CoverageBoundingBoxApiElement'
        h3_indices:
          $ref: '#/components/schemas/H3IndicesApiRequest'
    H3CoverageApiElement:
      title: H3 Coverage Information
      type: object
      properties:
        h3_id:
          title: H3 ID
          type: string
          description: H3 cell identifier
          format: uint64
        frame_count:
          title: Frame Count
          type: string
          description: Number of frames available in this H3 cell
          format: uint64
    GetH3CoverageResponse:
      title: H3 Coverage Response
      type: object
      properties:
        coverage:
          type: array
          items:
            $ref: '#/components/schemas/H3CoverageApiElement'
    apiFindRawFramesApiResult:
      title: VirtualCam Response
      type: object
      properties:
        frames:
          type: array
          items:
            $ref: '#/components/schemas/apiRawFrameApiElement'
        frames_fetched:
          title: Frames Fetched
          type: integer
          description: Frames fetched count
          format: int32
      example:
        frames:
        - frame_id: 56f8d643be2ff1e674598eccfae2b3e2
          frame_url: https://external-api.getnexar.com/aod/full/ride/cc07d59669bfa317a4136a7d93965b04/fod_709F23AE-6F53-49E8-A473-98FEB7DBE973.jpg
          camera_heading: 298.8096008300781
          captured_at: 1689242521198
          timezone_offset: -14400
          h3_index_res12: '631243922682792959'
          gps_info:
            longitude: -73.985751
            latitude: 40.733587
          thumbnail_url: https://external-api.getnexar.com/aod/thumbnail/ride/cc07d59669bfa317a4136a7d93965b04/fod_709F23AE-6F53-49E8-A473-98FEB7DBE973.jpg
          direction: NORTH_WEST
          frame_quality: 0.9148776531219482
          frame_context: NIGHTTIME
          osm_info:
            osm_node_id_from: 8310246171
            osm_node_id_to: 3985008876
            road_type: RESIDENTIAL
    apiRawFrameApiElement:
      title: Frame metadata
      type: object
      properties:
        frame_id:
          title: Frame ID
          type: string
          description: unique identifier of the frame
        frame_url:
          title: Frame full Path
          type: string
          description: URL to request the frame file (1280x720)
        thumbnail_url:
          title: Thumbnail of the frame full path
          type: string
          description: URL to request the thumbnail file (140x90)
        captured_at:
          title: Frame captured timestamp
          type: string
          description: Timestamp when the frame was captured (Epoch milliseconds)
          format: uint64
        timezone_offset:
          title: Timezone Offset
          type: integer
          description: Offset in seconds from UTC of the frame capture time
          format: int32
        h3_index_res12:
          title: H3 cell
          type: string
          description: H3 cell of resolution 12 where the frame is located
        gps_info:
          $ref: '#/components/schemas/road_itemapiGeoLocationApiElement'
        direction:
          $ref: '#/components/schemas/apiHeadingApiElement'
        camera_heading:
          title: Camera Heading
          type: number
          description: Course of the camera when the frame was captured
          format: double
        frame_quality:
          title: Frame Quality
          type: number
          description: Frame quality is defined as the number of pixels outside of the car divided by the total number of pixels.
          format: double
        frame_context:
          $ref: '#/components/schemas/apiDaylightStateApiElement'
        osm_info:
          $ref: '#/components/schemas/road_itemapiOsmRoadSegmentApiElement'
    apiFindRawFramesApiFilters:
      title: Request Filters
      type: object
      properties:
        directions:
          title: Directions
          type: array
          description: Filters frames according to the direction of the camera at the time the frame was captured
          items:
            $ref: '#/components/schemas/apiHeadingApiElement'
        frames_context:
          title: Frames Context
          type: array
          description: Filters frames according to daylight conditions
          items:
            $ref: '#/components/schemas/apiDaylightStateApiElement'
        min_frame_quality:
          title: Minimum Frame Quality
          type: number
          default: 0
          description: Filters frames according to a minimum frame quality. Frame quality is defined as the number of pixels outside of the car divided by the total number of pixels.
          format: double
        frames_per_h3:
          title: Frames per H3
          default: 5000
          type: integer
          description: Maximum number of frames to return per H3 in the response. The resolution of the H3 cell varies based on the requested area's size, with a range of resolution 3 for very large areas to resolution 12 for smaller areas.
          format: int64
        road_types:
          title: Road Types
          type: array
          description: Filters frames according to the OSM segment road type
          items:
            $ref: '#/components/schemas/road_itemapiOsmRoadTypeApiElement'
        start_time:
          title: Start timestamp
          type: string
          description: Filters frames which were captured after the specified start timestamp (Epoch milliseconds)
          format: uint64
        end_time:
          title: End Timestamp
          type: string
          description: Filters frames which were captured before the specified end timestamp (Epoch milliseconds)
          format: uint64
    apiDaylightStateApiElement:
      title: Daylight conditions
      type: string
      enum:
      - DAYLIGHT
      - TWILIGHT
      - NIGHTTIME
    HeadingApiElement:
      title: HeadingApiElement
      type: string
      description: Nexar car heading direction
      enum:
      - NORTH
      - NORTH_WEST
      - WEST
      - SOUTH_WEST
      - SOUTH
      - SOUTH_EAST
      - EAST
      - NORTH_EAST
    FindRawFramesApiFilters:
      title: Request Filters
      type: object
      properties:
        directions:
          title: Directions
          type: array
          description: Filters frames according to the direction of the camera at the time the frame was captured
          items:
            $ref: '#/components/schemas/HeadingApiElement'
        frames_context:
          title: Frames Context
          type: array
          description: Filters frames according to daylight conditions
          items:
            $ref: '#/components/schemas/DaylightStateApiElement'
        min_frame_quality:
          title: Minimum Frame Quality
          type: number
          description: Filters frames according to a minimum frame quality. Frame quality is defined as the number of pixels outside of the car divided by the total number of pixels.
          format: double
        frames_per_h3:
          title: Frames per H3
          type: integer
          description: Maximum number of frames to return per H3 in the response. The resolution of the H3 cell varies based on the requested area's size, with a range of resolution 3 for very large areas to resolution 12 for smaller areas.
          format: int64
        road_types:
          title: Road Types
          type: array
          description: Filters frames according to the OSM segment road type
          items:
            $ref: '#/components/schemas/OsmRoadTypeApiElement'
        start_time:
          title: Start timestamp
          type: string
          description: Filters frames which were captured after the specified start timestamp (Epoch milliseconds)
          format: uint64
        end_time:
          title: End Timestamp
          type: string
          description: Filters frames which were captured before the specified end timestamp (Epoch milliseconds)
          format: uint64
    FindRawFramesApiRequestParams:
      title: VirtualCam Request
      type: object
      properties:
        bounding_box:
          $ref: '#/components/schemas/GeoBoundingBoxApiElement'
        h3_location:
          $ref: '#/components/schemas/H3IndicesApiRequest'
        filters:
          $ref: '#/components/schemas/FindRawFramesApiFilters'
        sort_by:
          $ref: '#/components/schemas/SortByApiRequest'
    GeoBoundingBoxApiElement:
      title: Area of interest
      description: The geographical area of interest is defined as a rectangular area by its northeast and southwest points.
      type: object
      properties:
        north_east:
          $ref: '#/components/schemas/GeoLocationApiElement'
        south_west:
          $ref: '#/components/schemas/GeoLocationApiElement'
    FindRawFramesApiResponse:
      type: object
      properties:
        frames:
          type: array
          items:
            $ref: '#/components/schemas/RawFrameApiElement'
        frames_fetched:
          title: Frames Fetched
          type: integer
          description: Frames fetched count
          format: int32
    apiHeadingApiElement:
      title: HeadingApiElement
      type: string
      description: Camera direction
      enum:
      - NORTH
      - NORTH_WEST
      - WEST
      - SOUTH_WEST
      - SOUTH
      - SOUTH_EAST
      - EAST
      - NORTH_EAST
    DaylightStateApiElement:
      title: Daylight conditions
      type: string
      enum:
      - DAYLIGHT
      - TWILIGHT
      - NIGHTTIME
    apiSortByApiRequest:
      title: Optional sorting modes of the returned frame
      type: string
      default: TIMESTAMP
      enum:
      - TIMESTAMP
      - QUALITY
    RawFrameApiElement:
      title: Frame metadata
      type: object
      properties:
        frame_id:
          title: Frame ID
          type: string
          description: unique identifier of the frame
        frame_url:
          title: Frame full Path
          type: string
          description: URL to request the frame file (1280x720)
        thumbnail_url:
          title: Thumbnail of the frame full path
          type: string
          description: URL to request the thumbnail file (140x90)
        captured_at:
          title: Frame captured timestamp
          type: string
          description: Timestamp when the frame was captured (Epoch milliseconds)
          format: uint64
        timezone_offset:
          title: Timezone Offset
          type: integer
          description: Offset in seconds from UTC of the frame capture time
          format: int32
        h3_index_res12:
          title: H3 cell
          type: string
          description: H3 cell of resolution 12 where the frame is located
        gps_info:
          $ref: '#/components/schemas/GeoLocationApiElement'
        direction:
          $ref: '#/components/schemas/HeadingApiElement'
        camera_heading:
          title: Camera Heading
          type: number
          description: Course of the camera when the frame was captured
          format: double
        frame_quality:
          title: Frame Quality
          type: number
          description: Frame quality is defined as the number of pixels outside of the car divided by the total number of pixels.
          format: double
        frame_context:
          $ref: '#/components/schemas/DaylightStateApiElement'
        osm_info:
          $ref: '#/components/schemas/OsmRoadSegmentApiElement'
    H3IndicesApiRequest:
      title: Area of interest as H3 cells
      type: object
      description: Accepts H3 IDs with resolutions between 10 and 15 up to a maximum area equivalent to 1000 H3 cells of resolution 12.
      properties:
        h3_ids:
          title: H3 Ids
          type: array
          description: H3 IDs list in decimal format
          items:
            type: string
    SortByApiRequest:
      title: Optional sorting modes of the returned frame
      type: string
      description: Sorting modes for the request 'sort_by' optional param
      enum:
      - TIMESTAMP
      - QUALITY
    apiH3IndicesApiRequest:
      title: Area of interest as H3 cells
      type: object
      description: Accepts H3 IDs with resolutions between 10 and 15 up to a maximum area equivalent to 1000 H3 cells of resolution 12.
      properties:
        h3_ids:
          title: H3 Ids
          type: array
          description: H3 IDs list in decimal format
          items:
            type: string
    OsmRoadTypeApiElement:
      title: Open Street Map road types
      type: string
      enum:
      - MOTORWAY
      - TRUNK
      - PRIMARY
      - SECONDARY
      - TERTIARY
      - UNCLASSIFIED
      - RESIDENTIAL
      - SERVICE
      - MOTORWAY_LINK
      - TRUNK_LINK
      - PRIMARY_LINK
      - SECONDARY_LINK
      - TERTIARY_LINK
      - LIVING_STREET
      - PEDESTRIAN
      - TRACK
      - BUS_GUIDEWAY
      - ESCAPE
      - RACEWAY
      - ROAD
      - FOOTWAY
      - BRIDLEWAY
      - STEPS
      - PATH
      - CYCLEWAY
      - CONSTRUCTION
      - ABANDONED
      - ACCESS
      - PROPOSED
      - REST_AREA
    road_itemapiGeoLocationApiElement:
      title: GPS Point
      type: object
      properties:
        longitude:
          title: Longitude
          type: number
          description: GPS Point longitude in decimal degrees
          format: double
        latitude:
          title: Latitude
          type: number
          description: GPS Point latitude in decimal degrees
          format: double
    road_itemapiGeoBoundingBoxApiElement:
      title: Area of interest
      description: The geographical area of interest is defined as a rectangular area by its northeast and southwest points.
      type: object
      required:
      - north_east
      - south_west
      properties:
        north_east:
          $ref: '#/components/schemas/road_itemapiGeoLocationApiElement'
        south_west:
          $ref: '#/components/schemas/road_itemapiGeoLocationApiElement'
    GeoLocationApiElement:
      title: Geo Coordinates
      type: object
      properties:
        longitude:
          title: Longitude
          type: number
          description: GPS Point longitude in decimal degrees
          format: double
        latitude:
          title: Latitude
          type: number
          description: GPS Point latitude in decimal degrees
          format: double
    road_itemapiOsmRoadSegmentApiElement:
      title: Osm Info
      type: object
      properties:
        osm_node_id_from:
          type: string
          format: uint64
        osm_node_id_to:
          type: string
          format: uint64
        road_type:
          $ref: '#/components/schemas/road_itemapiOsmRoadTypeApiElement'
      description: Open Street Map way identifier and metadata
    nexarBadRequest:
      type: object
      title: Bad Request
      properties:
        status:
          type: integer
        error:
          type: string
      example:
        status: 400
        error: Bad Request
    road_itemapiOsmRoadTypeApiElement:
      title: Open Street Map road types
      type: string
      enum:
      - MOTORWAY
      - TRUNK
      - PRIMARY
      - SECONDARY
      - TERTIARY
      - UNCLASSIFIED
      - RESIDENTIAL
      - SERVICE
      - MOTORWAY_LINK
      - TRUNK_LINK
      - PRIMARY_LINK
      - SECONDARY_LINK
      - TERTIARY_LINK
      - LIVING_STREET
      - PEDESTRIAN
      - TRACK
      - BUS_GUIDEWAY
      - ESCAPE
      - RACEWAY
      - ROAD
      - FOOTWAY
      - BRIDLEWAY
      - STEPS
      - PATH
      - CYCLEWAY
      - CONSTRUCTION
      - ABANDONED
      - ACCESS
      - PROPOSED
      - REST_AREA
    H3CoverageBoundingBoxApiElement:
      title: H3 Coverage Area
      type: object
      properties:
        bounding_box:
          $ref: '#/components/schemas/GeoBoundingBoxApiElement'
        h3_resolution:
          title: H3 Resolution
          type: integer
          description: The resolution levels of H3 cells used to obtain coverage information - supported values are 3, 5, 7, 8, 9, 10, 11, and 12.
          format: int64
    apiFindRawFramesApiRequestParams:
      type: object
      title: VirtualCam Request
      properties:
        bounding_box:
          $ref: '#/components/schemas/road_itemapiGeoBoundingBoxApiElement'
        h3_location:
          $ref: '#/components/schemas/apiH3IndicesApiRequest'
        filters:
          $ref: '#/components/schemas/apiFindRawFramesApiFilters'
        sort_by:
          $ref: '#/components/schemas/apiSortByApiRequest'
      example:
        bounding_box:
          south_west:
            longitude: -73.99708049121774
            latitude: 40.72176834293103
          north_east:
            longitude: -73.98168795029027
            latitude: 40.73122344104337
        filters:
          frames_per_h3: 1
          min_frame_quality: 0.7
          road_types:
          - MOTORWAY
          - RESIDENTIAL
          frames_context:
          - DAYLIGHT
          - NIGHTTIME
          start_time: 1688169600000
          end_time: 1689206400000
        sort_by: QUALITY
    OsmRoadSegmentApiElement:
      title: Osm Info
      type: object
      properties:
        osm_node_id_from:
          type: string
          format: uint64
        osm_node_id_to:
          type: string
          format: uint64
        road_type:
          $ref: '#/components/schemas/OsmRoadTypeApiElement'
      description: Open Street Map way identifier and metadata
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header