HyperTrack

HyperTrack Geotags API

The Geotags API from HyperTrack — 2 operation(s) for geotags.

Documentation GitHub OpenAPI

Operations 2

GET /geotags/ Get Geotags

GET /geotags/{geotag_id} Get Geotag Timeline

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/hypertrack-geotags-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: HyperTrack Geotags API
  version: '1.0'
  description: HyperTrack API Reference — Orders, Workers, Places, Routes, and more.
  contact:
    name: HyperTrack support
    url: https://hypertrack.com/contact
    email: help@hypertrack.com
servers:
- url: https://v3.api.hypertrack.com
tags:
- name: Geotags
paths:
  /geotags/:
    get:
      parameters:
      - in: query
        name: order_handle
        description: String represent order identifier to fetch geotags associated with the identifier
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: worker_handle
        description: String representing the handle for the worker
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: driver_handle
        description: String representing the handle for the driver
        schema:
          type:
          - string
          - 'null'
          deprecated: true
        required: false
      - in: query
        name: ops_group_handles
        description: List of ops group handles as strings used for fetching associated Geotags
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: search_term
        description: String representing the search term. Search will be done on order_handle, ops_group_handle, worker_handle and metadata fields.
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: device_id
        description: String representing the ID of the device
        schema:
          type:
          - string
          - 'null'
          format: uuid
        required: false
      - in: query
        name: device_name
        description: Name of the worker provided during registration
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: driver_profile_filter
        description: JSON encoded string metadata associated with the worker who generated the geotag
        schema:
          type:
          - string
          - 'null'
          format: Encoded JSON
        required: false
      - in: query
        name: metadata_filter
        description: JSON encoded string metadata associated with the geotag
        schema:
          type:
          - string
          - 'null'
          format: Encoded JSON
        required: false
      - in: query
        name: system_generated_order_handle
        description: Boolean to filter out orders where order handle was automatically generated by HT system
        schema:
          type:
          - boolean
          - 'null'
        required: false
      - in: query
        name: include_system_generated_order_handle
        description: Flag to include orders where order handle was automatically generated by HT system.
        schema:
          type:
          - boolean
          - 'null'
        required: false
      - in: query
        name: region
        description: JSON encoded string for region
        schema:
          type:
          - string
          - 'null'
          format: Encoded JSON
        required: false
      - in: query
        name: pagination_token
        description: Identifier used to fetch the next page of data
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: from_time
        description: ISO 8601 datetime indicating the start time
        schema:
          type:
          - string
          - 'null'
          format: date-time
        required: false
      - in: query
        name: to_time
        description: ISO 8601 datetime indicating the end time
        schema:
          type:
          - string
          - 'null'
          format: date-time
        required: false
      - in: query
        name: from_date
        description: Start date (YYYY-MM-DD) of the time window used as a filter to retrieve geotags scheduled on a specific date, regardless of the timezone.
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: to_date
        description: End date (YYYY-MM-DD) of the time window used as a filter to retrieve geotags scheduled on a specific date, regardless of the timezone.
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: from_geotag_type
        description: String representing type of geotag which corresponds to start of time segment within the order fulfilled through geotags
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: to_geotag_type
        description: String representing type of geotag which corresponds to end of time segment within the order fulfilled through geotags
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: fetch_attachment_links
        description: Flag to return attachment links as part of response
        schema:
          type: boolean
          default: false
        required: false
      - in: query
        name: include_geotags_with_orders
        description: Flag to filter geotags which are part of order.
        schema:
          type:
          - boolean
          - 'null'
          default: false
        required: false
      - in: query
        name: aggregate
        description: Flag set to retrieve aggregated data over the provided time range
        schema:
          type: boolean
          default: false
        required: false
      - in: query
        name: limit
        description: Number of Orders to be sent in response
        schema:
          type:
          - integer
          - 'null'
          default: 100
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGeotagsResponse'
              examples:
                list_example:
                  summary: Get Orders List Fulfilled Using Geotags
                  value:
                    orders:
                    - order_handle: order-1
                      ops_group_handle: store-san-jose
                      system_generated_order_handle: false
                      device_id: 00112233-4455-6677-8899-AABBCCDDEEFF
                      worker_handle: james_smith
                      driver_name: James Smith
                      last_geotag_recorded_at: 2023-04-19 14:00:58+00:00
                      distance: 6529
                      duration: 10830
                      tracking_rate: 0.64
                      geotags:
                      - geotag_id: befe814d-79e5-44d5-ac03-c4e47e0931c9
                        order_handle: order-1
                        geotag_type: PICKUP
                        ops_group_handle: store-san-jose
                        system_generated_order_handle: false
                        recorded_at: 2023-04-19 14:00:58+00:00
                        device_id: 00112233-4455-6677-8899-AABBCCDDEEFF
                        worker_handle: james_smith
                        driver_name: James Smith
                        distance: 1729
                        duration: 8230
                        tracking_rate: 0.84
                        metadata:
                          regionId: 12234
                          zoneId: 3
                        location:
                          geometry:
                            type: Point
                            coordinates:
                            - -122.4285939
                            - 37.7598248
                          address: Dolores St &, 19th St, San Francisco, CA 94114
                        expected_location:
                          geometry:
                            type: Point
                            coordinates:
                            - -122.4297458
                            - 37.7617545
                          address: 3750 18th St, San Francisco, CA 94114
                        summary:
                          distance: 2300
                          duration: 1200
                          tracking_rate: 86.5
                          deviation: 500
                        start_location:
                          geometry:
                            type: Point
                            coordinates:
                            - -122.4526714
                            - 37.7652444
                          address: 941 Cole St, San Francisco, CA 94117
                        region:
                          city: San Francisco
                          state: California
                          country: United States of America
                      - geotag_id: f92s813d-5f33-8ks2-9j32-c8f44d59432b1
                        order_handle: order-1
                        geotag_type: ARRIVED
                        ops_group_handle: store-san-jose
                        system_generated_order_handle: false
                        recorded_at: 2023-04-19 14:30:58+00:00
                        device_id: 00112233-4455-6677-8899-AABBCCDDEEFF
                        worker_handle: james_smith
                        driver_name: James Smith
                        distance: 1800
                        duration: 2000
                        tracking_rate: 0.89
                        metadata:
                          regionId: 12234
                          zoneId: 3
                        location:
                          geometry:
                            type: Point
                            coordinates:
                            - -122.419329
                            - 37.752945
                          address: 2756 Mission St, San Francisco, CA 94110
                        expected_location:
                          geometry:
                            type: Point
                            coordinates:
                            - -122.4214724
                            - 37.7530874
                          address: 2740 Mission St, San Francisco, CA 94110
                        summary:
                          distance: 100
                          duration: 600
                          tracking_rate: 99.5
                          deviation: 100
                        start_location:
                          geometry:
                            type: Point
                            coordinates:
                            - -122.4526714
                            - 37.7652444
                          address: 941 Cole St, San Francisco, CA 94117
                        region:
                          city: San Francisco
                          state: California
                          country: United States of America
                      - geotag_id: ctfe813d-87v3-46d3-fd90-c8f44d59432b3
                        order_handle: order-1
                        geotag_type: COMPLETED
                        ops_group_handle: store-san-jose
                        system_generated_order_handle: false
                        recorded_at: 2023-04-19 14:30:58+00:00
                        device_id: 00112233-4455-6677-8899-AABBCCDDEEFF
                        worker_handle: james_smith
                        driver_name: James Smith
                        distance: 1800
                        duration: 2000
                        tracking_rate: 0.91
                        metadata:
                          regionId: 12234
                          zoneId: 3
                        location:
                          geometry:
                            type: Point
                            coordinates:
                            - -122.4214724
                            - 37.7530874
                          address: 2740 Mission St, San Francisco, CA 94110
                        expected_location:
                          geometry:
                            type: Point
                            coordinates:
                            - -122.4214724
                            - 37.7530874
                          address: 2740 Mission St, San Francisco, CA 94110
                        summary:
                          distance: 2300
                          duration: 1200
                          tracking_rate: 86.5
                          deviation: 0
                        start_location:
                          geometry:
                            type: Point
                            coordinates:
                            - -122.4526714
                            - 37.7652444
                          address: 941 Cole St, San Francisco, CA 94117
                        region:
                          city: San Francisco
                          state: California
                          country: United States of America
                    pagination_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWQiOiIxMDAiLCJwYWdpdGFudElkIjoiMTAwMDEiLCJhbWF6b25JZCI6IjEwMDAxIn0.9SEKO_8dk00Up2khdGkkgDl6OQg1uYUsbRMaj7TWl-4
                aggregate_example:
                  summary: Get Aggregates for Orders Fulfilled via Geotags
                  value:
                    aggregate:
                      count: 150
                      distance:
                        sum: 98000
                        mean: 654
                        min: 2000
                        max: 15000
                        stdev: 0.6
                        mean_by_driver: 2800
                      duration:
                        sum: 180000
                        mean: 1250
                        min: 600
                        max: 3600
                        stdev: 0.8
                        mean_by_driver: 800
                      geotags:
                        count: 450
                        count_mean: 3
                      tracking_rate: 98.4
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Geotags
      summary: Get Geotags
      description: Retrieves Geotags associated with orders. This API provides the ability to filter for Geotags based on a set of query parameters.
      security:
      - BasicAuth: []
      - TokenAuth: []
  /geotags/{geotag_id}:
    get:
      parameters:
      - in: path
        name: geotag_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGeotagTimelineResponse'
              example:
                geotag_id: befe814d-79e5-44d5-ac03-c4e47e0931c9
                order_handle: order-1
                geotag_type: PICKUP
                ops_group_handle: store-san-jose
                system_generated_order_handle: false
                recorded_at: 2023-04-19 14:00:58+00:00
                device_id: 00112233-4455-6677-8899-AABBCCDDEEFF
                worker_handle: james_smith
                driver_name: James Smith
                metadata:
                  regionId: 12234
                  zoneId: 3
                location:
                  geometry:
                    type: Point
                    coordinates:
                    - -122.3599933082254
                    - 37.753651385106075
                  address: Dolores St &, 19th St, San Francisco, CA 94114
                expected_location:
                  geometry:
                    type: Point
                    coordinates:
                    - -122.4297458
                    - 37.7617545
                  address: 3750 18th St, San Francisco, CA 94114
                distance: 2300
                duration: 1200
                tracking_rate: 86.5
                deviation: 500
                start_location:
                  geometry:
                    type: Point
                    coordinates:
                    - -122.4526714
                    - 37.7652444
                  address: 941 Cole St, San Francisco, CA 94117
                region:
                  city: San Francisco
                  state: California
                  country: United States of America
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      tags:
      - Geotags
      summary: Get Geotag Timeline
      description: Retrieve a geotag identified by the geotag_id.
      security:
      - BasicAuth: []
      - TokenAuth: []
components:
  schemas:
    DriveSummary:
      type: object
      properties:
        duration:
          type: integer
          description: Time duration in seconds worker spent during the activity
        count:
          type: integer
          description: Number of times the worker was observed in the activity
        distance:
          type: integer
          description: Distance covered by the worker while driving
      required:
      - count
      - distance
      - duration
    NoteAttachment1:
      type: object
      properties:
        type:
          type: string
          enum:
          - note
          description: Type of attachment
        data:
          type: string
          description: Text for the note
        attachment_id:
          type:
          - string
          - 'null'
      required:
      - data
      - type
    GeotagOrderAggregate:
      type: object
      properties:
        count:
          type: integer
          description: Number of orders generated in the given time range
        distance:
          description: Stats related to the orders distance
          allOf:
          - $ref: '#/components/schemas/GeotagStats'
        duration:
          description: Stats related to the orders duration in second
          allOf:
          - $ref: '#/components/schemas/GeotagStats'
        active_duration:
          description: Stats related to the orders active duration in second
          allOf:
          - $ref: '#/components/schemas/GeotagStats'
        outage_duration:
          description: Stats related to the orders outage duration in second
          allOf:
          - $ref: '#/components/schemas/GeotagStats'
        tracking_rate:
          type: number
          description: Tracking rate of the driver during the lifespan of the orders
        deviation:
          description: Stats related to the geotag deviation
          allOf:
          - $ref: '#/components/schemas/GeotagStats'
        geotags:
          description: Aggregate information of geotags
          allOf:
          - $ref: '#/components/schemas/GeotagAggregate'
        drivers:
          description: Aggregate information of drivers
          deprecated: true
          allOf:
          - $ref: '#/components/schemas/DriversAggregate'
        workers:
          description: Aggregate information of workers
          allOf:
          - $ref: '#/components/schemas/DriversAggregate'
        outage_summary:
          type:
          - array
          - 'null'
          description: List of outages experienced during the specified time range.
          items:
            $ref: '#/components/schemas/OrderOutageSummary'
      required:
      - count
    GeotagTrackingSummary:
      type: object
      properties:
        stop:
          description: Tracking summary of stops during the geotag lifespan.
          anyOf:
          - $ref: '#/components/schemas/ActivitySummary'
        walk:
          description: Tracking summary of walks during the geotag lifespan.
          anyOf:
          - $ref: '#/components/schemas/ActivitySummary'
        drive:
          description: Tracking summary of drives during the geotag lifespan.
          anyOf:
          - $ref: '#/components/schemas/DriveSummary'
    SignatureAttachment1:
      type: object
      properties:
        type:
          type: string
          enum:
          - signature
          description: Type of attachment
        url:
          type: string
          description: Signature image link
        attachment_id:
          type:
          - string
          - 'null'
      required:
      - type
      - url
    Region:
      type: object
      properties:
        country:
          type: string
          description: Country
        city:
          type:
          - string
          - 'null'
          description: City
        state:
          type:
          - string
          - 'null'
          description: State
      required:
      - country
    ValidationError:
      properties:
        detail:
          type: object
          properties:
            <location>:
              type: object
              properties:
                <field_name>:
                  type: array
                  items:
                    type: string
        message:
          type: string
      type: object
    GeotagStats:
      type: object
      properties:
        mean:
          type:
          - number
          - 'null'
          description: Average value for the metric
        min:
          type:
          - number
          - 'null'
          description: Minimum value for the metric
        max:
          type:
          - number
          - 'null'
          description: Maximum value for the metric
        stdev:
          type:
          - number
          - 'null'
          description: Standard deviation for the metric
        mean_by_driver:
          type:
          - number
          - 'null'
          description: Average value per worker for the metric
        sum:
          type: number
          description: Total value of the metric
      required:
      - sum
    LocationGeometry:
      type: object
      properties:
        type:
          type: string
          enum:
          - Point
          description: Geometry type
        coordinates:
          type: array
          description: Location coordinates represented as [longitude, latitude]
          items:
            type: number
      required:
      - coordinates
      - type
    LocationWithoutRadius:
      type: object
      properties:
        address:
          type:
          - string
          - 'null'
          description: Address for the location
        geometry:
          description: Location geometry
          anyOf:
          - $ref: '#/components/schemas/LocationGeometry'
    DriversAggregate:
      type: object
      properties:
        count:
          type: integer
          description: Total number of drivers
    OrderOutageSummary:
      type: object
      properties:
        duration:
          type: integer
          description: Sum total duration of all outages experienced with this `code` in the specified time range.
        distance:
          type: integer
          description: Sum total (estimated) distance covered during all outages experienced with this `code` in the specified time range.
        code:
          type: string
          description: Code indicating the type of outage
        label:
          type: string
          description: Text indicating the type of outage
        description:
          type: string
          description: Text describing the outage.
        category:
          type:
          - string
          - 'null'
          enum:
          - behavioural
          - adversarial
          - reachability
          - os
          - sporadic
          description: String indicating the category of outage
      required:
      - code
      - description
      - duration
      - label
    GeotagOrder:
      type: object
      properties:
        order_handle:
          type: string
          description: String representing the order
        last_geotag_recorded_at:
          type: string
          description: ISO 8601 date when the last geotag for the order was created
        distance:
          type: integer
          description: Distance travelled for the order
        duration:
          type: integer
          description: Duration to be tracked for the order
        driver_handle:
          type: string
          description: String representing the handle for the driver
          deprecated: true
        worker_handle:
          type: string
          description: String representing the handle for the worker
        driver_name:
          type: string
          description: String representing the name of the driver
          deprecated: true
        worker_name:
          type: string
          description: String representing the name of the driver
        device_id:
          type: string
          format: uuid
          description: String representing the ID of the device
        tracking_rate:
          type: number
          description: Driver tracking rate during the lifespan of the order
        ops_group_handle:
          type: string
          description: String representing the ops group handle
        system_generated_order_handle:
          type: boolean
          description: Boolean representing whether the handle was automatically generated by HT system or sent along with geotag data
        geotags:
          type: array
          description: List of geotags associated with order
          items:
            $ref: '#/components/schemas/Geotag'
      required:
      - device_id
      - distance
      - duration
      - last_geotag_recorded_at
      - order_handle
      - system_generated_order_handle
    ActivitySummary:
      type: object
      properties:
        duration:
          type: integer
          description: Time duration in seconds worker spent during the activity
        count:
          type: integer
          description: Number of times the worker was observed in the activity
      required:
      - count
      - duration
    HTTPError:
      properties:
        detail:
          type: object
        message:
          type: string
      type: object
    Geotag:
      type: object
      properties:
        geotag_id:
          type: string
          format: uuid
          description: Unique ID to identify a geotag
        driver_handle:
          type: string
          description: String representing the handle for the driver
          deprecated: true
        worker_handle:
          type: string
          description: String representing the handle for the worker
        recorded_at:
          type: string
          description: ISO 8601 date when the geotag was created
        device_id:
          type: string
          format: uuid
          description: String representing the ID of the device
        metadata:
          type: object
          description: Optional metadata associated with the geotag
          additionalProperties: {}
        location:
          description: Geometry location for a geotag
          allOf:
          - $ref: '#/components/schemas/LocationWithoutRadius'
        place_handle:
          type: string
          description: String representing the handle for the worker
        expected_location:
          description: Expected Geometry location for a geotag
          allOf:
          - $ref: '#/components/schemas/LocationWithoutRadius'
        start_location:
          description: Starting Geometry location point for a geotag
          allOf:
          - $ref: '#/components/schemas/LocationWithoutRadius'
        region:
          description: Region for a geotag
          allOf:
          - $ref: '#/components/schemas/Region'
        distance:
          type: integer
          description: Distance from the tracking start for the geotag
        duration:
          type: integer
          description: Time taken from start location to this geotag location
        deviation:
          type: integer
          description: Haversine deviation in meters from the expected location
        tracking_rate:
          type: number
          description: Driver tracking rate during the lifespan of the geotag
        geotag_type:
          type: string
          description: String representing type of Geotag
        order_handle:
          type: string
          description: String representing order handle with which the geotag is associated
        driver_name:
          type: string
          description: String representing the name of the driver
        ops_group_handle:
          type: string
          description: String representing the ops group handle
        system_generated_order_handle:
          type: boolean
          description: Boolean representing whether the handle was automatically generated by HT system or not
        timezone:
          type:
          - string
          - 'null'
          description: Timezone associated with this geotag
        attachments:
          type:
          - array
          - 'null'
          description: Attachments associated with this geotag
          items:
            oneOf:
            - $ref: '#/components/schemas/ImageAttachment1'
            - $ref: '#/components/schemas/NoteAttachment1'
            - $ref: '#/components/schemas/SignatureAttachment1'
        tracking_summary:
          description: Tracking summary of activities during the lifespan of geotag
          anyOf:
          - $ref: '#/components/schemas/GeotagTrackingSummary'
      required:
      - device_id
      - geotag_id
      - location
      - recorded_at
    GetGeotagsResponse:
      type: object
      properties:
        orders:
          type:
          - array
          - 'null'
          description: Array of Orders fulfilled in the given time range
          items:
            $ref: '#/components/schemas/GeotagOrder'
        pagination_token:
          type:
          - string
          - 'null'
          description: Identifier used to fetch the next page of data
        aggregate:
          description: Combined aggregate metrics for geotags and orders in the given time range
          anyOf:
          - $ref: '#/components/schemas/GeotagOrderAggregate'
    GetGeotagTimelineResponse:
      type: object
      properties:
        geotag_id:
          type: string
          format: uuid
          description: Unique ID to identify a geotag
        driver_handle:
          type: string
          description: String representing the handle for the driver
          deprecated: true
        worker_handle:
          type: string
          description: String representing the handle for the worker
        recorded_at:
          type: string
          description: ISO 8601 date when the geotag was created
        device_id:
          type: string
          format: uuid
          description: String representing the ID of the device
        metadata:
          type: object
          description: Optional metadata associated with the geotag
          additionalProperties: {}
        location:
          description: Geometry location for a geotag
          allOf:
          - $ref: '#/components/schemas/LocationWithoutRadius'
        place_handle:
          type: string
          description: String representing the handle for the worker
        expected_location:
          description: Expected Geometry location for a geotag
          allOf:
          - $ref: '#/components/schemas/LocationWithoutRadius'
        start_location:
          description: Starting Geometry location point for a geotag
          allOf:
          - $ref: '#/components/schemas/LocationWithoutRadius'
        region:
          description: Region for a geotag
          allOf:
          - $ref: '#/components/schemas/Region'
        distance:
          type: integer
          description: Distance from the tracking start for the geotag
        duration:
          type: integer
          description: Time taken from start location to this geotag location
        deviation:
          type: integer
          description: Haversine deviation in meters from the expected location
 

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hypertrack/refs/heads/main/openapi/hypertrack-geotags-api-openapi.yml