HyperTrack Places API

openapi: 3.2.0
info:
  title: HyperTrack Places 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: Places
paths:
  /places/v1/:
    get:
      parameters:
      - in: query
        name: place_handles
        description: List of place handles as comma separated strings used for fetching associated Places
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: search_term
        description: Keyword to match against place handle (or place id) OR name OR metadata
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: name
        description: Filter places by name (case-insensitive partial match)
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: lat
        description: latitude of location around which places should be searched
        schema:
          type:
          - number
          - 'null'
        required: false
      - in: query
        name: lon
        description: longitude of location around which places should be searched
        schema:
          type:
          - number
          - 'null'
        required: false
      - in: query
        name: radius
        description: radius around location which places should be searched, if given metadata is ignored
        schema:
          type:
          - integer
          - 'null'
        required: false
      - in: query
        name: metadata
        description: metadata of the order as json encoded string
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: min_skew
        description: Minimum skew to filter for. Skew in inferred geofence can be between 0 and 1. 0 mean no skew, i.e. perfect overlap and 1 means no overlap
        schema:
          type:
          - number
          - 'null'
        required: false
      - in: query
        name: sort_by
        description: Key on which result must be sorted.
        schema:
          type:
          - string
          - 'null'
          enum:
          - order_count
          - skew
          - last_updated
        required: false
      - in: query
        name: sort_direction
        description: Sort route responses by `asc` or `desc` on the created_at timestamp
        schema:
          type:
          - string
          - 'null'
          enum:
          - asc
          - desc
        required: false
      - in: query
        name: geofence_type
        description: Filter to fetch the specified geofence type.
        schema:
          type:
          - string
          - 'null'
          enum:
          - Point
          - Polygon
        required: false
      - in: query
        name: has_suggested_places
        description: Filter to fetch the places which has suggested geofences
        schema:
          type:
          - boolean
          - 'null'
        required: false
      - in: query
        name: suggestion_type
        description: 'Filter to fetch places by suggestion type. Comma-separated list of: ''manual'', ''inferred'', ''bounding_box'''
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: aggregate
        description: Whether to return aggregates, i.e. count of places
        schema:
          type:
          - boolean
          - 'null'
        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: limit
        description: Maximum number of results to be returned.
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        required: false
      - in: query
        name: from_date
        description: Start date (YYYY-MM-DD) of the time window used as a filter to retrieve places visited 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 places visited on a specific date, regardless of the timezone.
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: visit_detection_config
        description: Worker detection config as json encoded string
        schema:
          type:
          - string
          - 'null'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacesResponse'
          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:
      - Places
      summary: Get places
      description: Get places with filters. Response includes the 'name' field for each place if available.
      security:
      - BasicAuth: []
      - TokenAuth: []
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceResponse'
          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:
      - Places
      summary: Create a new Place in system
      description: Create a new place in hypertrack. The 'name' parameter allows you to provide a human-readable name for the place.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceCreateRequest'
      security:
      - BasicAuth: []
      - TokenAuth: []
  /places/v1/segments:
    get:
      parameters:
      - in: query
        name: segment
        description: Represents the segment used to retrieve the corresponding values
        schema:
          type: string
        required: true
      - in: query
        name: prefix
        description: Represents the prefix to be used when filtering segment values
        schema:
          type:
          - string
          - 'null'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPlaceSegmentsResponse'
              example:
                segments:
                - data:name
                - data:description
                - data:category
                truncated: false
          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:
      - Places
      summary: Get Place Segments
      description: Fetch segments from the place metadata that are associated with all metadata
      security:
      - BasicAuth: []
      - TokenAuth: []
  /places/v1/{place_handle}:
    get:
      parameters:
      - in: path
        name: place_handle
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceResponse'
          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:
      - Places
      summary: Get place by id
      description: Get place by id/handle. Response includes the 'name' field if available.
      security:
      - BasicAuth: []
      - TokenAuth: []
    patch:
      parameters:
      - in: path
        name: place_handle
        schema:
          type: string
        required: true
      - in: query
        name: update_associated_orders
        description: If true, updates all non-terminal orders associated with this place_handle to reflect the updated place destination.
        schema:
          type:
          - boolean
          - 'null'
          default: false
        required: false
      - in: query
        name: update_geometry_using_address
        description: If true, geocodes the place using the address provided in the request body and updates the geometry with the geocoded coordinates.
        schema:
          type:
          - boolean
          - 'null'
          default: false
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceResponse'
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Places
      summary: Updates a place
      description: 'Updates a place, send empty array to remove values for an array type parameter, null values will be ignored. eg. {"parkings": []} to clear parkings of a places instead of  {"parkings": null}. The ''name'' parameter can be updated to change the human-readable name of the place.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlacePatchRequest'
      security:
      - BasicAuth: []
      - TokenAuth: []
    delete:
      parameters:
      - in: path
        name: place_handle
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          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:
      - Places
      summary: Delete a place
      description: Delete a place
      security:
      - BasicAuth: []
      - TokenAuth: []
  /places/v1/{place_handle}/history:
    get:
      parameters:
      - in: path
        name: place_handle
        schema:
          type: string
        required: true
      - in: query
        name: pagination_token
        description: Identifier used to fetch the next page of data
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: limit
        description: Maximum number of results to return
        schema:
          type:
          - integer
          - 'null'
          default: 20
          minimum: 1
          maximum: 100
        required: false
      - in: query
        name: field_name
        description: 'Filter to show only changes related to a specific field. Allowed values: place_handle, name, geofence, metadata, parkings, checkins, timings, closed_on, expected_service_time, locked_from_suggestions'
        schema:
          type:
          - string
          - 'null'
          enum:
          - place_handle
          - name
          - geofence
          - metadata
          - parkings
          - checkins
          - timings
          - closed_on
          - expected_service_time
          - locked_from_suggestions
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceHistoryResponse'
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Places
      summary: Get place audit history
      description: Retrieve audit history for a place showing all changes over time with pagination. Use the field_name parameter to filter history to only show changes for a specific field.
      security:
      - BasicAuth: []
      - TokenAuth: []
  /places/v1/{place_handle}/suggestions/:
    get:
      parameters:
      - in: path
        name: place_handle
        schema:
          type: string
        required: true
      - in: query
        name: suggested_on_from
        description: Start timestamp (ISO 8601 format) to filter suggestions created on or after this time
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: suggested_on_to
        description: End timestamp (ISO 8601 format) to filter suggestions created on or before this time
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: pagination_token
        description: Identifier used to fetch the next page of suggestions
        schema:
          type:
          - string
          - 'null'
        required: false
      - in: query
        name: limit
        description: Maximum number of results to be returned.
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestionListResponse'
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Places
      summary: Get suggestions for a place
      description: Get suggestions for a place
      security:
      - BasicAuth: []
      - TokenAuth: []
    post:
      parameters:
      - in: path
        name: place_handle
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestionResponse'
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Places
      summary: Create a suggestion for a place
      description: Create a suggestion for a place
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestionCreateRequest'
      security:
      - BasicAuth: []
      - TokenAuth: []
  /places/v1/{place_handle}/inferences/clear:
    post:
      parameters:
      - in: path
        name: place_handle
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceResponse'
          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:
      - Places
      summary: Clear the inferences of a place
      description: Clears the inferences of a place, i.e. inferred geofences, parking, checking locations etc
      security:
      - BasicAuth: []
      - TokenAuth: []
  /places/v1/{place_handle}/suggestions/{suggestion_id}/apply:
    post:
      parameters:
      - in: path
        name: place_handle
        schema:
          type: string
        required: true
      - in: path
        name: suggestion_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestionResponse'
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Places
      summary: Apply a suggestion to a place
      description: Apply a suggestion to a place
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestionApplyRequest'
      security:
      - BasicAuth: []
      - TokenAuth: []
components:
  schemas:
    SuggestionApplyRequest:
      type: object
      properties:
        applied_by:
          type: string
          description: User who applied this suggestion
      required:
      - applied_by
    PlacePatchRequest:
      type: object
      properties:
        place_handle:
          type:
          - string
          - 'null'
          description: Human friendly handle of place
        name:
          type:
          - string
          - 'null'
          description: Human readable name of the place
        geometry:
          description: Location or geofence for this place
          oneOf:
          - $ref: '#/components/schemas/PointGeometry'
          - $ref: '#/components/schemas/PolygonGeometry'
        radius:
          type:
          - integer
          - 'null'
          description: Radius of geofence in case geometry is a Point
        address:
          type:
          - string
          - 'null'
          description: Address associated with the place
        timings:
          type:
          - array
          - 'null'
          description: Expected (open) timings for this place
          items:
            $ref: '#/components/schemas/ScheduleItem'
        metadata:
          type:
          - object
          - 'null'
          description: Metadata - any additional data in form of json
          additionalProperties: {}
        closed_on:
          type:
          - array
          - 'null'
          description: Dates when this place will be closed
          items:
            type: string
        expected_service_time:
          type:
          - integer
          - 'null'
          description: Expected service/work time at this place
        detect_visits:
          type:
          - boolean
          - 'null'
          deprecated: true
          description: 'DEPRECATED: This field is no longer supported and will be removed in a future version. Setting detect_visits to true will result in an error. Visit detection functionality has been discontinued. Use Orders API to detect visits to shift destinations instead.'
        geofence_id:
          type:
          - string
          - 'null'
          deprecated: true
          description: UUID of the associated geofence.
        address_components:
          description: 'Structured address components for more accurate geocoding. Fields: country, state, city, postal_code, street.'
          anyOf:
          - $ref: '#/components/schemas/AddressComponents'
        place_type:
          type:
          - string
          - 'null'
          enum:
          - shop
          - house
          - restaurant
          - office
          - warehouse
          - hospital
          - mall
          - university
          - golf_course
          - stadium
          - airport
          description: 'Type of place, used to restrict the maximum bounding box size during geocoding.


            | Type | Max Area | Approx. Size | Description |

            |------|----------|--------------|-------------|

            | shop | 5,000 m² | ~71m x 71m | Small retail shop or store |

            | house | 2,000 m² | ~45m x 45m | Residential house or apartment |

            | restaurant | 5,000 m² | ~71m x 71m | Restaurant, cafe, or eatery |

            | office | 10,000 m² | ~100m x 100m | Office building or coworking space |

            | warehouse | 50,000 m² | ~224m x 224m | Warehouse or distribution center |

            | hospital | 100,000 m² | ~316m x 316m | Hospital or large medical facility |

            | mall | 200,000 m² | ~447m x 447m | Shopping mall or large retail complex |

            | university | 5,000,000 m² | ~2.2km x 2.2km | University or large campus |

            | golf_course | 8,000,000 m² | ~2.8km x 2.8km | Golf course or large sports complex |

            | stadium | 1,000,000 m² | ~1.0km x 1.0km | Stadium or arena with parking |

            | airport | 8,000,000 m² | ~2.8km x 2.8km | Airport or airfield |


            If not specified, the default max area is 2,000,000 m² (~1.4km x 1.4km).'
        parkings:
          type:
          - array
          - 'null'
          description: Parkings around place
          items:
            $ref: '#/components/schemas/PlaceLocation'
        checkins:
          type:
          - array
          - 'null'
          description: Checkin or Clockin locations at place
          items:
            $ref: '#/components/schemas/PlaceLocation'
        visit_detection_config:
          description: Configuration as json to detect the visit based on the key value pair provided with it. This could be worker_handle or some logical grouping attached with worker's metadata.
          anyOf:
          - $ref: '#/components/schemas/VisitDetectionConfig'
        suggestion_used:
          type:
          - boolean
          - 'null'
          description: If the geofence is applied using inferred geofence or bounding box
        suggestion_id:
          type:
          - string
          - 'null'
          description: Id of the suggestion used to update the geofence
        locked_from_suggestions:
          type:
          - boolean
          - 'null'
          description: Whether this place is locked from receiving future suggestions. defaults to true if suggestion_used is false
        suggestions_reviewed_on:
          type:
          - string
          - 'null'
          description: Timestamp (ISO 8601) when suggestions were last reviewed for this place
    InferredGeofence:
      type: object
      properties:
        geometry:
          description: Location
          allOf:
          - $ref: '#/components/schemas/PolygonLocationGeometryResponse'
        source:
          enum:
          - customer_provided
          - ht_generated
          description: Source which created this location
        inclusivity:
          type: string
          description: More inclusivity means more loosely defined service area
        skew:
          type: number
          description: Skew in inferred geofence, values can be between 0 and 1. 0 mean no skew, i.e. perfect overlap and 1 means no overlap
        area_ratio:
          type:
          - number
          - 'null'
          description: Ratio of inferred geometry area to current geofence area (inferred/current)
        centroid_shift:
          type:
          - number
          - 'null'
          description: Distance in meters between the centroid of current geofence and inferred geometry
      required:
      - geometry
      - inclusivity
      - skew
      - source
    GetPlaceSegmentsResponse:
      type: object
      properties:
        segments:
          type: array
          description: Array of place segments associated with the account
          items:
            type: string
        truncated:
          type: boolean
          description: Flag indicating if segments are truncated
      required:
      - segments
      - truncated
    PlaceResponse:
      type: object
      properties:
        place_handle:
          type:
          - string
          - 'null'
          description: Human friendly handle of places
        name:
          type:
          - string
          - 'null'
          description: Human readable name of the place
        geometry:
          description: Location or geofence for this place
          oneOf:
          - $ref: '#/components/schemas/PointGeometry'
          - $ref: '#/components/schemas/PolygonGeometry'
        radius:
          type:
          - integer
          - 'null'
          description: Radius of geofence in case geometry is a Point
        address:
          type:
          - string
          - 'null'
          description: Address associated with the place
        timings:
          type:
          - array
          - 'null'
          description: Expected (open) timings for this place
          items:
            $ref: '#/components/schemas/ScheduleItem'
        metadata:
          type:
          - object
          - 'null'
          description: Metadata - any additional data in form of json
          additionalProperties: {}
        closed_on:
          type:
          - array
          - 'null'
          description: Dates when this place will be closed
          items:
            type: string
        expected_service_time:
          type:
          - integer
          - 'null'
          description: Expected service/work time at this place
        detect_visits:
          type:
          - boolean
          - 'null'
          deprecated: true
          description: 'DEPRECATED: This field is no longer supported and will be removed in a future version. Setting detect_visits to true will result in an error. Visit detection functionality has been discontinued. Use Orders API to detect visits to shift destinations instead.'
        geofence_id:
          type:
          - string
          - 'null'
          deprecated: true
          description: UUID of the associated geofence.
        address_components:
          description: 'Structured address components for more accurate geocoding. Fields: country, state, city, postal_code, street.'
          anyOf:
          - $ref: '#/components/schemas/AddressComponents'
        place_type:
          type:
          - string
          - 'null'
          enum:
          - shop
          - house
          - restaurant
          - office
          - warehouse
          - hospital
          - mall
          - university
          - golf_course
          - stadium
          - airport
          description: 'Type of place, used to restrict the maximum bounding box size during geocoding.


            | Type | Max Area | Approx. Size | Description |

            |------|----------|--------------|-------------|

            | shop | 5,000 m² | ~71m x 71m | Small retail shop or store |

            | house | 2,000 m² | ~45m x 45m | Residential house or apartment |

            | restaurant | 5,000 m² | ~71m x 71m | Restaurant, cafe, or eatery |

            | office | 10,000 m² | ~100m x 100m | Office building or coworking space |

            | warehouse | 50,000 m² | ~224m x 224m | Warehouse or distribution center |

            | hospital | 100,000 m² | ~316m x 316m | Hospital or large medical facility |

            | mall | 200,000 m² | ~447m x 447m | Shopping mall or large retail complex |

            | university | 5,000,000 m² | ~2.2km x 2.2km | University or large campus |

            | golf_course | 8,000,000 m² | ~2.8km x 2.8km | Golf course or large sports complex |

            | stadium | 1,000,000 m² | ~1.0km x 1.0km | Stadium or arena with parking |

            | airport | 8,000,000 m² | ~2.8km x 2.8km | Airport or airfield |


            If not specified, the default max area is 2,000,000 m² (~1.4km x 1.4km).'
        place_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Id of place
        last_updated:
          type:
          - string
          - 'null'
          description: Time when this place was last updated
        order_count:
          type:
          - integer
          - 'null'
          description: Order Count for this place
        inferred_geofences:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/InferredGeofence'
        inferred_geofences_skew:
          type:
          - number
          - 'null'
          description: Skew in inferred geofence, values can be between 0 and 1. 0 mean no skew, i.e. perfect overlap and 1 means no overlap
        visit_detection_config:
          description: Configuration as json to detect the visit based on the key value pair provided with it. This could be worker_handle or some logical grouping attached with worker's metadata.
          anyOf:
          - $ref: '#/components/schemas/VisitDetectionConfig'
        inferred_geofence:
          description: Inferred geofence as per the on ground activity on places
          anyOf:
          - $ref: '#/components/schemas/InferredGeofence'
        bounding_box:
          description: Bounding box for the location if the geometry of the place is a point
          anyOf:
          - $ref: '#/components/schemas/BoundingBox'
        created_by:
          description: Source details of who created this place
          anyOf:
          - $ref: '#/components/schemas/Source'
        updated_by:
          description: Source details of who last updated this place
          anyOf:
          - $ref: '#/components/schemas/Source'
        locked_from_suggestions:
          type:
          - boolean
          - 'nu

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