openapi: 3.0.1
info:
  contact:
    email: infrateam@zoox.com
    name: infra
    url: https://git.zooxlabs.com/zooxco/driving
  description:
    The geo service provides geo information that's required for operating
    a fleet within a region, including service areas, geofences, point of interests,
    etc. The geo service closely follows the terms defined by the ZRN.
  title: geo
  version: 2.0.0
servers:
  - url: /
paths:
  /points/:
    get:
      operationId: find_points
      parameters:
        - description: A list of point ids
          explode: false
          in: query
          name: ids
          required: true
          schema:
            items:
              type: integer
            type: array
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PointOfInterest"
          description: Operation was successful
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Points with the ids was not found
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Some internal server errors have occurred so retry it again
      summary: find points of interests
      x-openapi-router-controller: geo.controllers.default_controller
  /points/random/:
    get:
      operationId: generate_random_points
      parameters:
        - description: Id of the service area
          in: query
          name: service_area_id
          required: true
          schema:
            type: integer
        - description:
            Release status denotes the stage of the ZRN validation pipeline
            that a road network (or a road, a point) is in
          in: query
          name: release_status
          schema:
            $ref: "#/components/schemas/ReleaseStatus"
        - description:
            Whether a random point generator should return point of interest
            only or not.
          in: query
          name: point_of_interest_only
          schema:
            default: false
            type: boolean
        - description:
            The number of random points generated. Either the number of points
            or the travel time estimation should be passed in.
          in: query
          name: num_of_points
          schema:
            type: integer
        - description:
            The travel time estimation. Either the number of points or the
            travel time estimation should be passed in.
          in: query
          name: travel_time_seconds
          schema:
            type: number
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PointList"
          description: Operation was successful
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Service Area with the given id and release status is not found
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Some internal server errors have occurred so retry it again
      summary: Get random point within the service area
      x-openapi-router-controller: geo.controllers.default_controller
  /routes/:
    get:
      operationId: get_routes
      parameters:
        - in: query
          description: The start_location on which to filter on
          name: center
          schema:
            type: array
            items:
              type: number
              format: double
        - in: query
          description: Distance in meters from the origin to find the points
          name: radius
          schema:
            default: 10.0
            format: double
            minimum: 0
            type: number
        - description: Id of the service area
          in: query
          name: service_area_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoutesQueryResult"
          description: Operation was successful
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Invalid parameter was provided
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Some internal server error has occurred so retry it again
      summary: Retrieve the routes
      x-openapi-router-controller: geo.controllers.default_controller
  /routes/{route_id}:
    get:
      operationId: get_route_by_id
      parameters:
        - description: Id of the route
          in: path
          name: route_id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Route"
          description: Operation was successful
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Route with the id was not found
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Some internal server error has occurred so retry it again
      summary: Fetch the route by its ID
      x-openapi-router-controller: geo.controllers.default_controller
  /service-areas/:
    get:
      operationId: find_service_areas
      parameters:
        - description: A list of ids for fetching service areas
          explode: false
          in: query
          name: ids
          schema:
            items:
              type: integer
            type: array
          style: form
        - description:
            Release status denotes the stage of the ZRN validation pipeline
            that a road network (or a road, a point) is in
          in: query
          name: release_status
          schema:
            enum:
              - ALPHA
              - BETA
              - RELEASE
              - P2P
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceAreasQueryResult"
          description: Operation was successful
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Invalid parameter was provided
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
          description: Some internal server errors have occurred so retry it again
      summary: Query the service areas
      x-openapi-router-controller: geo.controllers.default_controller
components:
  parameters:
    ReleaseStatus:
      description:
        Release status denotes the stage of the ZRN validation pipeline
        that a road network (or a road, a point) is in
      in: query
      name: release_status
      schema:
        enum:
          - ALPHA
          - BETA
          - RELEASE
          - P2P
        type: string
  requestBodies:
    Route:
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/Route"
      required: true
  schemas:
    ServiceArea:
      description:
        An area where Zoox runs operations. Operations include but are
        not limited to R&D, geofence validation, pilot programs, and production services
      example:
        polygon:
          - [18.494211295267263, -127.23073270189397]
          - [18.494211295267263, -127.23073270189397]
        name: name
        id: 0
        point_of_interest_list:
          - display_location: [18.494211295267263, -127.23073270189397]
            name: name
            location: [18.494211295267263, -127.23073270189397]
            id: 0
          - display_location: [18.494211295267263, -127.23073270189397]
            name: name
            location: [18.494211295267263, -127.23073270189397]
            id: 0
      properties:
        id:
          description: Unique ID to identify the geofence
          readOnly: true
          type: integer
        name:
          description: Name of the service area
          type: string
        area_type:
          $ref: "#/components/schemas/AreaType"
        polygon:
          items:
            $ref: "#/components/schemas/Point"
          type: array
        point_of_interest_list:
          items:
            $ref: "#/components/schemas/PointOfInterest"
          type: array
        release_status:
          $ref: "#/components/schemas/ReleaseStatus"
      type: object
    ServiceAreasQueryResult:
      description: A list of service areas
      example:
        items:
          - polygon:
              - point_of_interest_name: point_of_interest_name
                point_of_interest_id: 5
                latitude: 18.494211295267263
                longitude: -127.23073270189397
              - point_of_interest_name: point_of_interest_name
                point_of_interest_id: 5
                latitude: 18.494211295267263
                longitude: -127.23073270189397
            name: name
            id: 0
            point_of_interest_list:
              - display_location:
                  point_of_interest_name: point_of_interest_name
                  point_of_interest_id: 5
                  latitude: 18.494211295267263
                  longitude: -127.23073270189397
                name: name
                location:
                  point_of_interest_name: point_of_interest_name
                  point_of_interest_id: 5
                  latitude: 18.494211295267263
                  longitude: -127.23073270189397
                id: 0
              - display_location:
                  point_of_interest_name: point_of_interest_name
                  point_of_interest_id: 5
                  latitude: 18.494211295267263
                  longitude: -127.23073270189397
                name: name
                location:
                  point_of_interest_name: point_of_interest_name
                  point_of_interest_id: 5
                  latitude: 18.494211295267263
                  longitude: -127.23073270189397
                id: 0
          - polygon:
              - point_of_interest_name: point_of_interest_name
                point_of_interest_id: 5
                latitude: 18.494211295267263
                longitude: -127.23073270189397
              - point_of_interest_name: point_of_interest_name
                point_of_interest_id: 5
                latitude: 18.494211295267263
                longitude: -127.23073270189397
            name: name
            id: 0
            point_of_interest_list:
              - display_location:
                  point_of_interest_name: point_of_interest_name
                  point_of_interest_id: 5
                  latitude: 18.494211295267263
                  longitude: -127.23073270189397
                name: name
                location:
                  point_of_interest_name: point_of_interest_name
                  point_of_interest_id: 5
                  latitude: 18.494211295267263
                  longitude: -127.23073270189397
                id: 0
              - display_location:
                  point_of_interest_name: point_of_interest_name
                  point_of_interest_id: 5
                  latitude: 18.494211295267263
                  longitude: -127.23073270189397
                name: name
                location:
                  point_of_interest_name: point_of_interest_name
                  point_of_interest_id: 5
                  latitude: 18.494211295267263
                  longitude: -127.23073270189397
                id: 0
      properties:
        items:
          description: Provides a list of service areas
          items:
            $ref: "#/components/schemas/ServiceArea"
          type: array
      type: object
    PointOfInterest:
      description:
        A point that has special operational meaning, e.g. serves as a
        PU/DO location in a service area.
      properties:
        id:
          description: Unique id for a point
          type: integer
        name:
          type: string
        location:
          $ref: "#/components/schemas/Point"
        display_location:
          $ref: "#/components/schemas/Point"
      type: object
    PointList:
      description: A list of points
      items:
        $ref: "#/components/schemas/Point"
      type: array
    Point:
      description:
        A geo data structure in (latitude, longitude) tuple. It's
        the building block for other geo data structures.
      example:
        [18.494211295267263, -127.23073270189397]
      type: array
      items:
        type: number
        format: float
      minItems: 2
    ReleaseStatus:
      description:
        The release status describes at what stage the underling map of
        this area is with regard to the map validation process
      enum:
        - ALPHA
        - BETA
        - RELEASE
        - P2P
      type: string
    AreaType:
      description:
        The area type annotates what types of service is enabled or disabled
        for an operational area
      enum:
        - INVALID_TYPE
        - P2P
        - RESTRICTED
        - PICKUPS_EXCLUDED
        - OUT_OF_ODD
      type: string
    ErrorInfo:
      description: Resource representing the error information
      properties:
        status_code:
          description: Error code
          readOnly: true
          type: integer
        message:
          description: Detail info representing the error
          readOnly: true
          type: string
      type: object
    Route:
      description: Provides the information for a route
      example:
        destinationName: destinationName
        requireSmoothing: true
        origin: [5.962133916683182, 5.637376656633329]
        name: name
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        serviceAreaId: 7
        originName: originName
        destination:
          altitudeMeters: 2.3021358869347655
          latitude: 5.962133916683182
          longitude: 5.637376656633329
        waypoints:
          - altitudeMeters: 2.3021358869347655
            latitude: 5.962133916683182
            longitude: 5.637376656633329
          - altitudeMeters: 2.3021358869347655
            latitude: 5.962133916683182
            longitude: 5.637376656633329
      properties:
        id:
          description: Unique ID to identify the resource
          format: uuid
          readOnly: true
          type: string
        name:
          description: Name of the route
          type: string
        origin:
          $ref: "#/components/schemas/Point"
        originName:
          description: Name for the origin
          type: string
        destination:
          $ref: "#/components/schemas/Point"
        destinationName:
          description: Name for the destination
          type: string
        waypoints:
          items:
            $ref: "#/components/schemas/Point"
          type: array
        serviceAreaId:
          description: The id of the service area that the route belongs to
          type: integer
        requireSmoothing:
          description: Whether the route needs to be smoothed for visualization
          type: boolean
      required:
        - destination
        - name
        - origin
      type: object
    ListMetaData:
      description: Provides the meta data for various list resources
      example:
        orderBy: orderBy
        totalCount: 1
        direction: ASCENDING
      properties:
        orderBy:
          description: Resource's property on which resources are sorted
          type: string
        direction:
          description: Direction of the sorting order
          enum:
            - ASCENDING
            - DESCENDING
          type: string
        totalCount:
          description: Total number of resources available
          type: integer
      required:
        - direction
        - orderBy
        - totalCount
      type: object
    RoutesQueryResult:
      description: Provides a list resource for routes
      example:
        metaData:
          orderBy: orderBy
          totalCount: 1
          direction: ASCENDING
        items:
          - destinationName: destinationName
            requireSmoothing: true
            origin:
              altitudeMeters: 2.3021358869347655
              latitude: 5.962133916683182
              longitude: 5.637376656633329
            name: name
            id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
            serviceAreaId: 7
            originName: originName
            destination:
              altitudeMeters: 2.3021358869347655
              latitude: 5.962133916683182
              longitude: 5.637376656633329
            waypoints:
              - altitudeMeters: 2.3021358869347655
                latitude: 5.962133916683182
                longitude: 5.637376656633329
              - altitudeMeters: 2.3021358869347655
                latitude: 5.962133916683182
                longitude: 5.637376656633329
          - destinationName: destinationName
            requireSmoothing: true
            origin:
              altitudeMeters: 2.3021358869347655
              latitude: 5.962133916683182
              longitude: 5.637376656633329
            name: name
            id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
            serviceAreaId: 7
            originName: originName
            destination:
              altitudeMeters: 2.3021358869347655
              latitude: 5.962133916683182
              longitude: 5.637376656633329
            waypoints:
              - altitudeMeters: 2.3021358869347655
                latitude: 5.962133916683182
                longitude: 5.637376656633329
              - altitudeMeters: 2.3021358869347655
                latitude: 5.962133916683182
                longitude: 5.637376656633329
      properties:
        metaData:
          $ref: "#/components/schemas/ListMetaData"
        items:
          items:
            $ref: "#/components/schemas/Route"
          type: array
      required:
        - items
        - metaData
      type: object
