openapi: 3.2.0
info:
  title: CityStream™ Work Zones Get a collection of work zones API
  description: "The CityStream™ Work Zones API provides a curated collection of work zones that the Nexar's AI detects from images with road work elements (e.g. grabber cones, diamond signs, barriers or message boards). \n\n Before you start developing with the CityStream™ Work Zones API, make sure you have a valid Access Token."
  contact:
    name: Nexar
    url: https://getnexar.com/
    email: api-support@getnexar.com
  license:
    name: 'License: Proprietary'
  version: '3.0'
servers:
- url: https://external.getnexar.com
security:
- Bearer: []
tags:
- name: Get a collection of work zones
paths:
  /api/workzones/v3/detections:
    post:
      tags:
      - Get a collection of work zones
      summary: Get a set of curated work zone detections.
      description: Get curated work zone detections by element and road type from a geographical area defined as bounding box or H3 IDs (Hexagonal Hierarchical Spatial Index).
      operationId: NexarPlatformAPI_FindDetections
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/nexarFindDetectionsRequestParams'
        required: true
      responses:
        200:
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/nexarFindDetectionsResponse'
        403:
          description: There's a problem with your request Authorization (Insufficient permissions)
          content:
            application/json:
              schema:
                type: object
        500:
          description: Something is broken. This is usually a temporary error due to high server load or a brief endpoint error.
          content:
            application/json:
              schema:
                type: object
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/runtimeError'
      security:
      - Bearer: []
      x-codegen-request-body-name: body
components:
  schemas:
    nexarOsmInfo:
      title: Open Street Map way identifier and metadata
      type: object
      properties:
        osm_node_id_from:
          type: string
          format: uint64
        osm_node_id_to:
          type: string
          format: uint64
        road_type:
          $ref: '#/components/schemas/nexarRoadType'
      example:
        osm_node_id_from: '5717622395'
        osm_node_id_to: '5717622398'
        road_type: SECONDARY
    FindDetectionsRequestParamsSortDirection:
      title: Sort order
      type: string
      default: NONE
      enum:
      - NONE
      - ASC
      - DESC
    nexarH3IndicesRequest:
      title: List of Uber H3 hexagon identifiers
      type: object
      properties:
        h3_indices:
          title: H3 Id
          type: array
          description: Uber H3 hexagon identifiers list
          items:
            type: string
      example:
        h3_indices:
        - '622236750708604927'
        - '622236723640434687'
    nexarConstructionZoneDetectionElement:
      type: object
      properties:
        element:
          $ref: '#/components/schemas/nexarRoadBlockageConstructionElement'
        evidence_frames:
          title: Evidence Frames
          type: array
          description: List of evidence frames showing the construction element
          items:
            $ref: '#/components/schemas/nexarRoadItemEvidenceFrame'
    nexarGeoLine:
      title: Geo line
      type: object
      properties:
        point_from:
          $ref: '#/components/schemas/nexarGPSPoint'
        point_to:
          $ref: '#/components/schemas/nexarGPSPoint'
        course:
          title: Nexar car heading value
          type: number
          format: double
        osm_info:
          $ref: '#/components/schemas/nexarOsmInfo'
    nexarConstructionZoneDetectionSegment:
      title: Construction elements that ConstructionZoneSegmentconstitute a construction zone grouped to a primary road segment
      type: object
      properties:
        segment:
          $ref: '#/components/schemas/mobinexarConstructionZoneSegment'
        sub_item_id:
          $ref: '#/components/schemas/nexarObjectId'
        detection_element:
          $ref: '#/components/schemas/nexarConstructionZoneDetectionElement'
    nexarFindDetectionsRequestParams:
      title: Work Zones Request Parameters
      required:
      - detection_filter
      - time_range
      type: object
      properties:
        detection_filter:
          $ref: '#/components/schemas/nexarRoadItemDetectionFilter'
        bounding_box:
          $ref: '#/components/schemas/nexarBoundingGPSBox'
        h3_indices:
          $ref: '#/components/schemas/nexarH3IndicesRequest'
        heading:
          $ref: '#/components/schemas/nexarHeading'
        time_range:
          $ref: '#/components/schemas/mobinexarTimeRange'
        time_sort_direction:
          $ref: '#/components/schemas/FindDetectionsRequestParamsSortDirection'
        limit:
          title: Limit
          type: integer
          description: Page limit for returned detection results
          format: int64
        start:
          title: Start
          type: integer
          description: Start offset for paged detection results
          format: int64
        time_of_day_range:
          $ref: '#/components/schemas/nexarTimeOfDayRange'
      example:
        detection_filter:
          construction_zone_filter:
            construction_zone_elements:
              elements:
              - TRAFFIC_CONE
              - TRAFFIC_CONE_BLACK
              - ARROW_BOARD
              - MESSAGE_BOARD
            construction_zone_impact:
              lane_impact:
              - BLOCKED
              - NEW_BLOCKAGE
              - EXISTING_BLOCKAGE
              - REMOVED_BLOCKAGE
          status:
          - EXISTING_DETECTION
        bounding_box:
          south_west_point:
            longtitude: -118.41187389888535
            latitude: 33.68281897686988
          north_east_point:
            longtitude: -117.89828178052616
            latitude: 34.023717915748875
        time_range:
          end: 1671624519242
        limit: 10
    nexarConstructionZoneRoadSegment:
      title: Describes the impact on a lane from a given construction zone
      type: object
      properties:
        segment:
          $ref: '#/components/schemas/mobinexarConstructionZoneSegment'
        status:
          $ref: '#/components/schemas/nexarChangeDetectionStatus'
    runtimeError:
      type: object
      properties:
        error:
          type: string
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    nexarConstructionZoneElements:
      title: Filter predicate by work zone element type
      type: object
      properties:
        elements:
          title: Construction Elements
          type: array
          description: List of construction zone elements
          items:
            $ref: '#/components/schemas/nexarRoadBlockageConstructionElement'
        operator:
          $ref: '#/components/schemas/nexarLogicalOperator'
        not:
          title: Not
          type: boolean
          description: Negation operator (e.g. NOT TRAFFIC_CONE)
    nexarHeading:
      title: heading
      type: string
      description: Nexar car heading direction
      default: UNKNOWN_HEADING
      enum:
      - UNKNOWN_HEADING
      - NORTH
      - NORTH_WEST
      - WEST
      - SOUTH_WEST
      - SOUTH
      - SOUTH_EAST
      - EAST
      - NORTH_EAST
    nexarRoadItemDetectionResultSet:
      type: object
      properties:
        road_item_detections:
          title: Road Item Detections
          type: array
          description: Road item detection results
          items:
            $ref: '#/components/schemas/nexarRoadItemDetection'
        total_row_count:
          title: Total Row Count
          type: integer
          description: Count of total rows
          format: int64
        fetch_count:
          title: Fetch Count
          type: integer
          description: Count of rows in result set (current page)
          format: int64
        result_window_time_range:
          $ref: '#/components/schemas/mobinexarTimeRange'
    nexarFindDetectionsResponse:
      title: find detections response
      type: object
      properties:
        results:
          $ref: '#/components/schemas/nexarRoadItemDetectionResultSet'
    nexarConstructionZoneImpact:
      title: Filter predicate by impact on road
      type: object
      properties:
        lane_impact:
          title: Lane Impact
          type: array
          description: Impact of construction elements on road (e.g. BLOCKED)
          items:
            $ref: '#/components/schemas/nexarConstructionZoneImpactLaneImpact'
        not:
          title: Not
          type: boolean
          description: Negation operator (e.g. NOT BLOCKED)
    nexarTimeOfDayRange:
      title: Filter predicate by time of day
      type: object
      properties:
        from:
          $ref: '#/components/schemas/nexarTimeOfDay'
        to:
          $ref: '#/components/schemas/nexarTimeOfDay'
        time_zone_name:
          title: IANA full time zone name e.g. America/Los_Angeles
          type: string
    nexarRoadBlockageConstructionElement:
      title: Construction element types
      type: string
      default: UNKNOWN_CONSTRUCTION_ELEMENT
      enum:
      - UNKNOWN_CONSTRUCTION_ELEMENT
      - BARRIER
      - CONE
      - POLE
      - DIAMOND_SIGN
      - RECTANGULAR_SIGN
      - TRAFFIC_CONE
      - GRABBER_CONE
      - DRUM
      - BARRICADE
      - OTHER_CONSTRUCTION_AND_SAFETY_ELEMENT
      - ARROW_OR_MESSAGE_BOARD
      - NO_ARROW_OR_MESSAGE_BOARD
      - ARROW_BOARD
      - MESSAGE_BOARD
      - TRAFFIC_CONE_BLACK
      - VERTICAL_PANEL
      - ROAD_WORKS_SIGN_VIENNA
    nexarGPSPoint:
      title: A basic GPS point
      type: object
      properties:
        latitude:
          title: Latitude
          type: number
          description: GPS Point latitude
          format: double
        longtitude:
          title: Longiutde
          type: number
          description: GPS Point longitude
          format: double
        altitude:
          title: Altitude
          type: number
          description: GPS Point altitude
          format: double
      example:
        latitude: 40.7380653
        longtitude: -73.9800164
    nexarBoundingGPSBox:
      title: Geo bounding box
      required:
      - north_east_point
      - south_west_point
      type: object
      properties:
        south_west_point:
          $ref: '#/components/schemas/nexarGPSPoint'
        north_east_point:
          $ref: '#/components/schemas/nexarGPSPoint'
    nexarConstructionZoneImpactLaneImpact:
      type: string
      default: NO_IMPACT
      enum:
      - NO_IMPACT
      - BLOCKED
      - NEW_BLOCKAGE
      - EXISTING_BLOCKAGE
      - REMOVED_BLOCKAGE
    mobinexarConstructionZoneDetection:
      title: Aggregated construction zone detections segmented by geographical shape
      type: object
      properties:
        primary_segments:
          title: Primary Segments
          type: array
          description: Primary segments are road areas which are blocked by construction zone
          items:
            $ref: '#/components/schemas/nexarConstructionZoneRoadSegment'
        detection_segments:
          title: Detection Segments
          type: array
          description: Detection segments are where construction zone elements (such as Barrels, Traffic cone, etc) were detected.
          items:
            $ref: '#/components/schemas/nexarConstructionZoneDetectionSegment'
    nexarRoadItemEvidenceFrame:
      type: object
      properties:
        frame_id:
          title: Frame Id
          type: string
          description: Unique frame identifier
        image_ref:
          title: Image Ref
          type: string
          description: URL to the frame
        raw_gps_signal_of_camera:
          $ref: '#/components/schemas/nexarGPSSignal'
        location_of_camera:
          $ref: '#/components/schemas/nexarGPSPoint'
        course_of_camera:
          title: Course Of Camera
          type: number
          description: Course of the camera capturing the frame
          format: double
        detection_locations:
          title: Detection Locations
          type: array
          description: List of detection locations of a given type in this frame
          items:
            $ref: '#/components/schemas/nexarDetectionLocation'
        h3_indices:
          $ref: '#/components/schemas/nexarPointH3Indices'
        osm_info:
          $ref: '#/components/schemas/nexarOsmInfo'
    nexarPointH3Indices:
      title: Uber H3 index list
      type: object
      properties:
        h3_index_res0:
          title: Res0
          type: string
          description: H3 resolution 0 identifier
        h3_index_res1:
          title: Res1
          type: string
          description: H3 resolution 1 identifier
        h3_index_res2:
          title: Res2
          type: string
          description: H3 resolution 2 identifier
        h3_index_res3:
          title: Res3
          type: string
          description: H3 resolution 3 identifier
        h3_index_res4:
          title: Res4
          type: string
          description: H3 resolution 4 identifier
        h3_index_res5:
          title: Res5
          type: string
          description: H3 resolution 5 identifier
        h3_index_res6:
          title: Res6
          type: string
          description: H3 resolution6 identifier
        h3_index_res7:
          title: Res7
          type: string
          description: H3 resolution 7 identifier
        h3_index_res8:
          title: Res08
          type: string
          description: H3 resolution 8 identifier
        h3_index_res9:
          title: Res9
          type: string
          description: H3 resolution 9 identifier
        h3_index_res10:
          title: Res10
          type: string
          description: H3 resolution 10 identifier
        h3_index_res11:
          title: Res11
          type: string
          description: H3 resolution 11 identifier
        h3_index_res12:
          title: Res12
          type: string
          description: H3 resolution 12 identifier
        h3_index_res13:
          title: Res13
          type: string
          description: H3 resolution 13 identifier
        h3_index_res14:
          title: Res14
          type: string
          description: H3 resolution 14 identifier
        h3_index_res15:
          title: Res15
          type: string
          description: H3 resolution 15 identifier
      example:
        h3_index_res0: '577199624117288959'
        h3_index_res1: '581698825698148351'
        h3_index_res2: '586198577034821631'
        h3_index_res3: '590702107942715391'
        h3_index_res4: '595205690390216703'
        h3_index_res5: '599709288943845375'
        h3_index_res6: '604212888034344959'
        h3_index_res7: '608716487544274943'
        h3_index_res8: '613220087161159679'
        h3_index_res9: '617723686786695167'
        h3_index_res10: '622227286413836287'
        h3_index_res11: '626730886041182207'
        h3_index_res12: '631234485668551679'
        h3_index_res13: '635738085295921855'
        h3_index_res14: '640241684923292319'
        h3_index_res15: '644745284550662814'
    nexarTimeOfDay:
      title: Time of day
      type: object
      properties:
        hours:
          title: 0 to 23
          type: integer
          format: int32
        minutes:
          title: 0 to 59
          type: integer
          format: int32
        seconds:
          title: 0 to 59
          type: integer
          format: int32
      example:
        hours: 22
        minutes: 10
        seconds: 0
    nexarGPSSignal:
      title: GPS measurement
      type: object
      properties:
        timestamp:
          title: Timestamp
          type: string
          description: Timestamp in milliseconds (UTC)
          format: uint64
        longitude:
          title: Longitude
          type: number
          description: GPS Point longitude
          format: double
        latitude:
          title: Latitude
          type: number
          description: GPS Point latitude
          format: double
        horizontal_accuracy:
          title: Horizontal Accuracy
          type: number
          description: GPS horizontal accuracy in meters
          format: double
        vertical_accuracy:
          title: Vertical Accuracy
          type: number
          description: GPS vertical accuracy in Meters
          format: double
        altitude:
          title: Altitude
          type: number
          description: GPS detected altitude
          format: double
        speed:
          title: Speed
          type: number
          description: GPS detected speed in meters per second
          format: double
        course:
          title: Course
          type: number
          description: GPS heading direction
          format: double
        producer:
          $ref: '#/components/schemas/GPSSignalGPSProducer'
        gps_timestamp:
          type: string
          format: int64
        producer_timestamp:
          type: string
          format: int64
      example:
        latitude: 40.7380653
        longtitude: -73.9800164
        timestamp: 1562979339998
        horizontal_accuracy: 8.0012082736
        course: 6.91280832
        altitude: 725.5895027
        speed: 11.34940719
    mobinexarConstructionZoneSegment:
      type: object
      properties:
        line:
          $ref: '#/components/schemas/nexarGeoLine'
        lane_impact:
          $ref: '#/components/schemas/nexarConstructionZoneImpactLaneImpact'
      description: Construction zones are segmented geographically. Each segment is described by a geographical line.
    nexarRoadType:
      title: Open Street Map road types
      type: string
      default: UNKNOWN_ROAD_TYPE
      enum:
      - UNKNOWN_ROAD_TYPE
      - 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
    nexarRoadItemDetection:
      type: object
      title: Work Zone detection
      properties:
        item_id:
          $ref: '#/components/schemas/nexarObjectId'
        construction_zone:
          $ref: '#/components/schemas/mobinexarConstructionZoneDetection'
        timezone_offset:
          title: Timezone Offset
          type: integer
          description: Timezone offset in seconds from UTC
          format: int32
        created_at_millis:
          title: Created at millis
          type: string
          description: UTC Timestamp in milliseconds of the earliest evidence
          format: uint64
        expired_at_millis:
          title: expired at millis
          type: string
          description: UTC Timestamp in milliseconds of the detection expiration
          format: uint64
    nexarChangeDetectionStatus:
      title: Describing the status of the work zone lane impact (e.g. new / removed detections)
      type: string
      default: DETECTION_STATUS_NONE
      enum:
      - DETECTION_STATUS_NONE
      - NEW_DETECTION
      - EXISTING_DETECTION
      - REMOVED_DETECTION
    nexarObjectId:
      title: Wrapper for Nexar unique identifier
      type: object
      properties:
        id:
          type: string
      example:
        id: bed8dfe80331c3062c6893ac8c08146d
    nexarDetectionLocation:
      title: Detection location and metadata
      type: object
      properties:
        location:
          $ref: '#/components/schemas/nexarGPSPoint'
        course:
          title: Course
          type: number
          description: Aggregated course of the detection
          format: double
        bbox:
          $ref: '#/components/schemas/nexarBBox'
        confidence:
          title: Confidence
          type: number
          description: Detection confidence
          format: double
        h3_indices:
          $ref: '#/components/schemas/nexarPointH3Indices'
    nexarRoadItemDetectionFilter:
      type: object
      title: Detection filters
      properties:
        construction_zone_filter:
          $ref: '#/components/schemas/nexarConstructionZoneFilter'
        status:
          title: Status
          type: array
          description: Change detection status filter
          items:
            $ref: '#/components/schemas/nexarChangeDetectionStatus'
    protobufAny:
      type: object
      properties:
        type_url:
          type: string
          description: "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n  value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n  URL, or have them precompiled into a binary to avoid any\n  lookup. Therefore, binary compatibility needs to be preserved\n  on changes to types. (Use versioned type names to manage\n  breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
        value:
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          description: Must be a valid serialized protocol buffer of the above specified type.
          format: byte
      description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n    Foo foo = ...;\n    Any any;\n    any.PackFrom(foo);\n    ...\n    if (any.UnpackTo(&foo)) {\n      ...\n    }\n\nExample 2: Pack and unpack a message in Java.\n\n    Foo foo = ...;\n    Any any = Any.pack(foo);\n    ...\n    if (any.is(Foo.class)) {\n      foo = any.unpack(Foo.class);\n    }\n\n Example 3: Pack and unpack a message in Python.\n\n    foo = Foo(...)\n    any = Any()\n    any.Pack(foo)\n    ...\n    if any.Is(Foo.DESCRIPTOR):\n      any.Unpack(foo)\n      ...\n\n Example 4: Pack and unpack a message in Go\n\n     foo := &pb.Foo{...}\n     any, err := ptypes.MarshalAny(foo)\n     ...\n     foo := &pb.Foo{}\n     if err := ptypes.UnmarshalAny(any, foo); err != nil {\n       ...\n     }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n    package google.profile;\n    message Person {\n      string first_name = 1;\n      string last_name = 2;\n    }\n\n    {\n      \"@type\": \"type.googleapis.com/google.profile.Person\",\n      \"firstName\": <string>,\n      \"lastName\": <string>\n    }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n    {\n      \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n      \"value\": \"1.212s\"\n    }"
    nexarBBox:
      title: Location of detected element on the image, where (X1,Y1),(X2,Y2) describes the SW,NE corners accordingly
      type: object
      properties:
        x1:
          type: number
          format: double
        y1:
          type: number
          format: double
        x2:
          type: number
          format: double
        y2:
          type: number
          format: double
        tag:
          type: string
      example:
        x1: 246
        y1: 426
        x2: 290
        y2: 492
        tag: grabber_cone
    GPSSignalGPSProducer:
      title: GPS signal source (Camera or external mount)
      type: string
      default: DEVICE
      enum:
      - DEVICE
      - CAMERA_MOUNT
    nexarLogicalOperator:
      title: Conjunction operator
      type: string
      default: OR
      enum:
      - OR
      - AND
    mobinexarTimeRange:
      title: Work Zones filter by their detection time
      description: Selects detections within the aggregation time window which delimited by the end timestamp
      type: object
      required:
      - end
      properties:
        start:
          title: Deprecated
          type: string
          format: uint64
        end:
          title: Time range end date (UTC)
          type: string
          format: uint64
      example:
        start: 1585468974791
        end: 1588060974791
    nexarConstructionZoneFilter:
      title: Filter by work zone elements type / impact on road
      type: object
      properties:
        construction_zone_elements:
          $ref: '#/components/schemas/nexarConstructionZoneElements'
        construction_zone_impact:
          $ref: '#/components/schemas/nexarConstructionZoneImpact'
        operator:
          $ref: '#/components/schemas/nexarLogicalOperator'
          not: null
          title: Not
          type: boolean
          description: Negation operator (e.g. NOT construction_zone_elements)
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header