openapi: 3.0.3
info:
  title: Radar API
  description: >-
    Radar is a geofencing and maps platform. The Radar API provides forward and
    reverse geocoding, IP geocoding, address and place search with autocomplete,
    geofence search, routing (distance, matrix, directions, and route matching),
    geofence management, user (device) tracking, events, trips, address
    verification, and map tiles. All requests are authenticated with an
    Authorization header containing a publishable (client) key prefixed
    `prj_live_pk_` / `prj_test_pk_` or a secret (server) key prefixed
    `prj_live_sk_` / `prj_test_sk_`.
  termsOfService: https://radar.com/terms
  contact:
    name: Radar Support
    email: support@radar.com
    url: https://radar.com/documentation
  version: '1.0'
servers:
  - url: https://api.radar.io/v1
    description: Radar production API
security:
  - RadarKey: []
tags:
  - name: Geocoding
    description: Forward, reverse, and IP geocoding.
  - name: Search
    description: Address and place autocomplete, place search, and geofence search.
  - name: Routing
    description: Distance, matrix, directions, and route matching.
  - name: Geofences
    description: Create, read, update, and delete geofences.
  - name: Track
    description: Track device location and manage users.
  - name: Events
    description: List and manage geofence and place events.
  - name: Trips
    description: Create, update, and list trips for trip tracking.
  - name: Addresses
    description: Validate and verify addresses.
  - name: Tiles
    description: Raster and vector map tiles.
paths:
  /geocode/forward:
    get:
      operationId: forwardGeocode
      tags:
        - Geocoding
      summary: Forward geocode an address.
      description: Geocodes an address, converting an address string to coordinates.
      parameters:
        - name: query
          in: query
          required: true
          description: The address to geocode.
          schema:
            type: string
          example: 841 Broadway, New York, NY 10003
        - name: layers
          in: query
          required: false
          description: Optional comma-separated layers to filter (e.g. address, postalCode, locality).
          schema:
            type: string
        - name: country
          in: query
          required: false
          description: Optional comma-separated ISO 3166 country codes to filter.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodeResponse'
  /geocode/reverse:
    get:
      operationId: reverseGeocode
      tags:
        - Geocoding
      summary: Reverse geocode coordinates.
      description: Reverse geocodes a location, converting coordinates to an address.
      parameters:
        - name: coordinates
          in: query
          required: true
          description: The latitude and longitude to reverse geocode, comma-separated.
          schema:
            type: string
          example: 40.73430,-73.99110
        - name: layers
          in: query
          required: false
          description: Optional comma-separated layers to filter.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodeResponse'
  /geocode/ip:
    get:
      operationId: ipGeocode
      tags:
        - Geocoding
      summary: IP geocode.
      description: >-
        Geocodes the requester's IP address (or an explicitly provided IP) to a
        city, state, and country.
      parameters:
        - name: ip
          in: query
          required: false
          description: Optional IP address to geocode. Defaults to the requester IP.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpGeocodeResponse'
  /search/autocomplete:
    get:
      operationId: autocomplete
      tags:
        - Search
      summary: Autocomplete addresses and places.
      description: Autocompletes partial addresses and place names, returning ranked suggestions.
      parameters:
        - name: query
          in: query
          required: true
          description: The partial address or place to autocomplete.
          schema:
            type: string
          example: 841 Broadway
        - name: near
          in: query
          required: false
          description: Optional latitude,longitude to bias results toward.
          schema:
            type: string
          example: 40.70390,-73.98730
        - name: limit
          in: query
          required: false
          description: The maximum number of results (default 10, max 100).
          schema:
            type: integer
            default: 10
        - name: layers
          in: query
          required: false
          description: Optional comma-separated layers to filter (e.g. address, street, locality, place).
          schema:
            type: string
        - name: countryCode
          in: query
          required: false
          description: Optional ISO 3166 country code to filter.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteResponse'
  /search/places:
    get:
      operationId: searchPlaces
      tags:
        - Search
      summary: Search for places.
      description: >-
        Searches for places near a location, filtered by chain, category, or
        Radar place group.
      parameters:
        - name: near
          in: query
          required: true
          description: The latitude,longitude to search near.
          schema:
            type: string
          example: 40.78382,-73.97536
        - name: radius
          in: query
          required: false
          description: The radius to search within, in meters (max 10000).
          schema:
            type: integer
            default: 1000
        - name: chains
          in: query
          required: false
          description: Optional comma-separated chain slugs to filter (e.g. starbucks).
          schema:
            type: string
        - name: categories
          in: query
          required: false
          description: Optional comma-separated categories to filter (e.g. food-beverage).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: The maximum number of results (default 10, max 100).
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceSearchResponse'
  /search/geofences:
    get:
      operationId: searchGeofences
      tags:
        - Search
      summary: Search for geofences.
      description: Searches for geofences near a location, filtered by tag and metadata.
      parameters:
        - name: near
          in: query
          required: true
          description: The latitude,longitude to search near.
          schema:
            type: string
          example: 40.78382,-73.97536
        - name: radius
          in: query
          required: false
          description: The radius to search within, in meters (max 10000).
          schema:
            type: integer
            default: 1000
        - name: tags
          in: query
          required: false
          description: Optional comma-separated geofence tags to filter.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: The maximum number of results (default 100, max 1000).
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofenceListResponse'
  /route/distance:
    get:
      operationId: routeDistance
      tags:
        - Routing
      summary: Calculate travel distance and duration.
      description: >-
        Calculates the travel distance and duration between an origin and a
        destination for one or more travel modes.
      parameters:
        - name: origin
          in: query
          required: true
          description: The origin latitude,longitude.
          schema:
            type: string
          example: 40.78382,-73.97536
        - name: destination
          in: query
          required: true
          description: The destination latitude,longitude.
          schema:
            type: string
          example: 40.70390,-73.98730
        - name: modes
          in: query
          required: true
          description: Comma-separated travel modes (foot, bike, car, truck, motorbike).
          schema:
            type: string
          example: car,foot
        - name: units
          in: query
          required: false
          description: The distance units (metric or imperial).
          schema:
            type: string
            enum:
              - metric
              - imperial
            default: imperial
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DistanceResponse'
  /route/matrix:
    get:
      operationId: routeMatrix
      tags:
        - Routing
      summary: Calculate a distance matrix.
      description: >-
        Calculates travel distances and durations between multiple origins and
        destinations.
      parameters:
        - name: origins
          in: query
          required: true
          description: Pipe-separated list of origin latitude,longitude pairs.
          schema:
            type: string
          example: 40.78382,-73.97536|40.70390,-73.98730
        - name: destinations
          in: query
          required: true
          description: Pipe-separated list of destination latitude,longitude pairs.
          schema:
            type: string
          example: 40.73430,-73.99110|40.75080,-73.99340
        - name: mode
          in: query
          required: true
          description: The travel mode (foot, bike, car, truck, motorbike).
          schema:
            type: string
          example: car
        - name: units
          in: query
          required: false
          description: The distance units (metric or imperial).
          schema:
            type: string
            enum:
              - metric
              - imperial
            default: imperial
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatrixResponse'
  /route/directions:
    get:
      operationId: routeDirections
      tags:
        - Routing
      summary: Get turn-by-turn directions.
      description: >-
        Returns turn-by-turn directions and route geometry between a series of
        locations.
      parameters:
        - name: locations
          in: query
          required: true
          description: Pipe-separated list of latitude,longitude waypoints.
          schema:
            type: string
          example: 40.78382,-73.97536|40.70390,-73.98730
        - name: mode
          in: query
          required: true
          description: The travel mode (foot, bike, car, truck, motorbike).
          schema:
            type: string
          example: car
        - name: units
          in: query
          required: false
          description: The distance units (metric or imperial).
          schema:
            type: string
            enum:
              - metric
              - imperial
            default: imperial
        - name: geometry
          in: query
          required: false
          description: The geometry encoding (linestring, polyline, or polyline6).
          schema:
            type: string
            default: linestring
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectionsResponse'
  /route/match:
    post:
      operationId: routeMatch
      tags:
        - Routing
      summary: Match a GPS trace to roads.
      description: >-
        Snaps a sequence of noisy GPS coordinates to the road network and
        returns the matched route.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteMatchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectionsResponse'
  /geofences:
    get:
      operationId: listGeofences
      tags:
        - Geofences
      summary: List geofences.
      description: Lists geofences, sorted by creation date descending.
      parameters:
        - name: tag
          in: query
          required: false
          description: Optional geofence tag to filter.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: The maximum number of geofences (default 100, max 1000).
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofenceListResponse'
  /geofences/{tag}/{externalId}:
    put:
      operationId: upsertGeofence
      tags:
        - Geofences
      summary: Create or update a geofence.
      description: Creates or updates a geofence identified by a tag and external ID.
      parameters:
        - name: tag
          in: path
          required: true
          description: The geofence tag.
          schema:
            type: string
        - name: externalId
          in: path
          required: true
          description: The external ID that uniquely identifies the geofence within the tag.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeofenceUpsertRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofenceResponse'
    get:
      operationId: getGeofence
      tags:
        - Geofences
      summary: Get a geofence.
      description: Retrieves a geofence by tag and external ID.
      parameters:
        - name: tag
          in: path
          required: true
          schema:
            type: string
        - name: externalId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofenceResponse'
    delete:
      operationId: deleteGeofence
      tags:
        - Geofences
      summary: Delete a geofence.
      description: Deletes a geofence by tag and external ID.
      parameters:
        - name: tag
          in: path
          required: true
          schema:
            type: string
        - name: externalId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /track:
    post:
      operationId: track
      tags:
        - Track
      summary: Track a device location.
      description: >-
        Tracks a device's location server-side, generating events and updating
        the user. Requires a secret key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackResponse'
  /users:
    get:
      operationId: listUsers
      tags:
        - Track
      summary: List users.
      description: Lists users, sorted by last updated descending.
      parameters:
        - name: limit
          in: query
          required: false
          description: The maximum number of users (default 100, max 1000).
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
  /users/{userId}:
    get:
      operationId: getUser
      tags:
        - Track
      summary: Get a user.
      description: Retrieves a user by Radar ID or external ID.
      parameters:
        - name: userId
          in: path
          required: true
          description: The Radar _id, or an external ID prefixed with externalId=.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
    delete:
      operationId: deleteUser
      tags:
        - Track
      summary: Delete a user.
      description: Deletes a user and associated location data.
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /events:
    get:
      operationId: listEvents
      tags:
        - Events
      summary: List events.
      description: Lists geofence, place, and trip events, sorted by creation date descending.
      parameters:
        - name: limit
          in: query
          required: false
          description: The maximum number of events (default 100, max 1000).
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResponse'
  /events/{eventId}:
    get:
      operationId: getEvent
      tags:
        - Events
      summary: Get an event.
      description: Retrieves an event by ID.
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
  /trips:
    get:
      operationId: listTrips
      tags:
        - Trips
      summary: List trips.
      description: Lists trips, sorted by creation date descending.
      parameters:
        - name: status
          in: query
          required: false
          description: Optional trip status to filter (started, approaching, arrived, completed, canceled, expired).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripListResponse'
  /trips/{externalId}:
    post:
      operationId: upsertTrip
      tags:
        - Trips
      summary: Create or update a trip.
      description: Creates or updates a trip identified by an external ID.
      parameters:
        - name: externalId
          in: path
          required: true
          description: The external ID that uniquely identifies the trip.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TripUpsertRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripResponse'
    get:
      operationId: getTrip
      tags:
        - Trips
      summary: Get a trip.
      description: Retrieves a trip by external ID.
      parameters:
        - name: externalId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripResponse'
    patch:
      operationId: updateTrip
      tags:
        - Trips
      summary: Update a trip.
      description: Updates the status or metadata of an existing trip.
      parameters:
        - name: externalId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TripUpdateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripResponse'
  /addresses/validate:
    get:
      operationId: validateAddress
      tags:
        - Addresses
      summary: Validate an address.
      description: >-
        Validates and standardizes an address, returning a verification status
        and standardized components.
      parameters:
        - name: countryCode
          in: query
          required: true
          description: The ISO 3166 country code.
          schema:
            type: string
          example: US
        - name: stateCode
          in: query
          required: false
          schema:
            type: string
          example: NY
        - name: city
          in: query
          required: false
          schema:
            type: string
          example: New York
        - name: postalCode
          in: query
          required: false
          schema:
            type: string
          example: '10003'
        - name: number
          in: query
          required: false
          schema:
            type: string
          example: '841'
        - name: street
          in: query
          required: false
          schema:
            type: string
          example: Broadway
        - name: addressLabel
          in: query
          required: false
          description: A full single-line address to validate.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
  /maps/tiles/{z}/{x}/{y}.png:
    get:
      operationId: getRasterTile
      tags:
        - Tiles
      summary: Get a raster map tile.
      description: Returns a raster (PNG) map tile for the given zoom, x, and y coordinates.
      parameters:
        - name: z
          in: path
          required: true
          description: The zoom level.
          schema:
            type: integer
        - name: x
          in: path
          required: true
          schema:
            type: integer
        - name: 'y'
          in: path
          required: true
          schema:
            type: integer
        - name: style
          in: query
          required: false
          description: The map style (e.g. radar-default-v1, radar-light-v1, radar-dark-v1).
          schema:
            type: string
            default: radar-default-v1
        - name: scale
          in: query
          required: false
          description: The tile scale (1 or 2 for retina).
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: OK
          content:
            image/png:
              schema:
                type: string
                format: binary
components:
  securitySchemes:
    RadarKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        A Radar publishable (client) key (prj_live_pk_... / prj_test_pk_...) or
        secret (server) key (prj_live_sk_... / prj_test_sk_...), passed in the
        Authorization header without a Bearer prefix.
  schemas:
    Meta:
      type: object
      properties:
        code:
          type: integer
          example: 200
    Address:
      type: object
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        geometry:
          type: object
          properties:
            type:
              type: string
              example: Point
            coordinates:
              type: array
              items:
                type: number
        country:
          type: string
        countryCode:
          type: string
        state:
          type: string
        stateCode:
          type: string
        city:
          type: string
        postalCode:
          type: string
        number:
          type: string
        street:
          type: string
        addressLabel:
          type: string
        formattedAddress:
          type: string
        layer:
          type: string
        confidence:
          type: string
    GeocodeResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
    IpGeocodeResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        ip:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        proxy:
          type: boolean
    AutocompleteResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
    Place:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        categories:
          type: array
          items:
            type: string
        chain:
          type: object
          properties:
            name:
              type: string
            slug:
              type: string
        location:
          type: object
          properties:
            type:
              type: string
              example: Point
            coordinates:
              type: array
              items:
                type: number
    PlaceSearchResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        places:
          type: array
          items:
            $ref: '#/components/schemas/Place'
    Geofence:
      type: object
      properties:
        _id:
          type: string
        description:
          type: string
        tag:
          type: string
        externalId:
          type: string
        type:
          type: string
          enum:
            - circle
            - polygon
            - isochrone
        geometryCenter:
          type: object
          properties:
            type:
              type: string
              example: Point
            coordinates:
              type: array
              items:
                type: number
        geometryRadius:
          type: integer
        enabled:
          type: boolean
        metadata:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    GeofenceUpsertRequest:
      type: object
      required:
        - description
        - type
      properties:
        description:
          type: string
        type:
          type: string
          enum:
            - circle
            - polygon
            - isochrone
        coordinates:
          type: array
          description: For circle, [longitude, latitude]. For polygon, an array of [lng, lat] pairs.
          items: {}
        radius:
          type: integer
          description: The radius in meters (for circle geofences).
        enabled:
          type: boolean
          default: true
        metadata:
          type: object
          additionalProperties: true
    GeofenceResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        geofence:
          $ref: '#/components/schemas/Geofence'
    GeofenceListResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        geofences:
          type: array
          items:
            $ref: '#/components/schemas/Geofence'
    RouteLeg:
      type: object
      properties:
        distance:
          type: object
          properties:
            value:
              type: number
            text:
              type: string
        duration:
          type: object
          properties:
            value:
              type: number
            text:
              type: string
    DistanceResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        routes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RouteLeg'
    MatrixResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        origins:
          type: array
          items:
            type: object
        destinations:
          type: array
          items:
            type: object
        matrix:
          type: array
          description: A 2D array of route legs indexed by origin then destination.
          items:
            type: array
            items:
              $ref: '#/components/schemas/RouteLeg'
    DirectionsResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        routes:
          type: array
          items:
            type: object
            properties:
              distance:
                type: object
              duration:
                type: object
              geometry:
                type: object
              legs:
                type: array
                items:
                  type: object
    RouteMatchRequest:
      type: object
      required:
        - coordinates
        - mode
      properties:
        coordinates:
          type: array
          description: An ordered list of [longitude, latitude] GPS points.
          items:
            type: array
            items:
              type: number
        mode:
          type: string
          example: car
        timestamps:
          type: array
          description: Optional UNIX timestamps aligned with coordinates.
          items:
            type: integer
    Location:
      type: object
      properties:
        type:
          type: string
          example: Point
        coordinates:
          type: array
          items:
            type: number
    User:
      type: object
      properties:
        _id:
          type: string
        userId:
          type: string
        deviceId:
          type: string
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
        location:
          $ref: '#/components/schemas/Location'
        locationAccuracy:
          type: number
        geofences:
          type: array
          items:
            $ref: '#/components/schemas/Geofence'
        place:
          $ref: '#/components/schemas/Place'
        updatedAt:
          type: string
          format: date-time
    TrackRequest:
      type: object
      required:
        - deviceId
        - latitude
        - longitude
        - accuracy
      properties:
        deviceId:
          type: string
        userId:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        accuracy:
          type: number
        foreground:
          type: boolean
        stopped:
          type: boolean
        deviceType:
          type: string
        metadata:
          type: object
          additionalProperties: true
    Event:
      type: object
      properties:
        _id:
          type: string
        type:
          type: string
          example: user.entered_geofence
        live:
          type: boolean
        user:
          $ref: '#/components/schemas/User'
        geofence:
          $ref: '#/components/schemas/Geofence'
        place:
          $ref: '#/components/schemas/Place'
        confidence:
          type: integer
        createdAt:
          type: string
          format: date-time
    TrackResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        user:
          $ref: '#/components/schemas/User'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    UserResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        user:
          $ref: '#/components/schemas/User'
    UserListResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    EventResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        event:
          $ref: '#/components/schemas/Event'
    EventListResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    Trip:
      type: object
      properties:
        _id:
          type: string
        externalId:
          type: string
        status:
          type: string
          enum:
            - started
            - approaching
            - arrived
            - completed
            - canceled
            - expired
        mode:
          type: string
        destinationGeofenceTag:
          type: string
        destinationGeofenceExternalId:
          type: string
        metadata:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    TripUpsertRequest:
      type: object
      properties:
        userId:
          type: string
        mode:
          type: string
          example: car
        destinationGeofenceTag:
          type: string
        destinationGeofenceExternalId:
          type: string
        approachingThreshold:
          type: integer
        metadata:
          type: object
          additionalProperties: true
    TripUpdateRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - started
            - approaching
            - arrived
            - completed
            - canceled
            - expired
        metadata:
          type: object
          additionalProperties: true
    TripResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        trip:
          $ref: '#/components/schemas/Trip'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    TripListResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        trips:
          type: array
          items:
            $ref: '#/components/schemas/Trip'
    AddressValidationResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        address:
          $ref: '#/components/schemas/Address'
        result:
          type: object
          properties:
            verificationStatus:
              type: string
              enum:
                - verified
                - partially verified
                - ambiguous
                - unverified