--- title: "Get places" method: GET path: "/places/v1/" tags: ["Places"] --- # Get places `GET /places/v1/` ## Request - Base URL: `https://v3.api.hypertrack.com` - URL: `https://v3.api.hypertrack.com/places/v1/` - Auth: one of: - HTTP basic - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Get places with filters. Response includes the 'name' field for each place if available. ## Query parameters - `place_handles` string, nullable - `search_term` string, nullable - `name` string, nullable - `lat` number, nullable - `lon` number, nullable - `radius` integer, nullable - `metadata` string, nullable - `min_skew` number, nullable - `sort_by` 'order_count' | 'skew' | 'last_updated' | 'null', nullable - `sort_direction` 'asc' | 'desc' | 'null', nullable - `geofence_type` 'Point' | 'Polygon' | 'null', nullable - `has_suggested_places` boolean, nullable - `suggestion_type` string, nullable - `aggregate` boolean, nullable - `pagination_token` string, nullable - `limit` integer, nullable - `from_date` string, nullable - `to_date` string, nullable - `visit_detection_config` string, nullable ## Response `200` Successful response - PlacesResponse - `aggregate` union: Places aggregate results, if aggregate flag is passed in request - PlacesAggregate - `count` integer, required: Total number of places found - `count_circular_places` integer, required: Number of places with circular geofence - `count_polygon_places` integer, required: Number of places with polygon geofence - unknown - `places` PlaceListResponse[], nullable: List of places - `place_handle` string, nullable: Human friendly handle of places - `name` string, nullable: Human readable name of the place - `geometry` union, required: Location or geofence for this place - PointGeometry - `coordinates` number[], required: Location coordinates represented as [longitude, latitude] - `type` 'Point': Geometry type - PolygonGeometry - `type` 'Polygon', required: Geometry type - `coordinates` array[], required: Location coordinates represented as [[[longitude, latitude], [lon, lat]...]] - array[] - number[] - `radius` integer, nullable: Radius of geofence in case geometry is a Point - `address` string, nullable: Address associated with the place - `timings` ScheduleItem[], nullable: Expected (open) timings for this place - `day_of_week` 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY' | 'SUNDAY', required: Day of week - `start_time` string, required: Start time (opening time) for the day - `end_time` string, required: end_time (closing time) for the day - `metadata` object, nullable: Metadata - any additional data in form of json - `closed_on` string[], nullable: Dates when this place will be closed - `expected_service_time` integer, nullable: Expected service/work time at this place - `detect_visits` boolean, nullable: 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` string, nullable: UUID of the associated geofence. - `address_components` union: Structured address components for more accurate geocoding. Fields: country, state, city, postal_code, street. - AddressComponents - `country` string, nullable: Country name or code - `state` string, nullable: State or province - `city` string, nullable: City or town - `postal_code` string, nullable: Postal/ZIP code - `street` string, nullable: Street address - unknown - `place_type` 'shop' | 'house' | 'restaurant' | 'office' | 'warehouse' | 'hospital' | 'mall' | 'university' | 'golf_course' | 'stadium' | 'airport' | 'null', nullable: 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` string, uuid, nullable: Id of place - `last_updated` string, nullable: Time when this place was last updated - `order_count` integer, nullable: Order Count for this place - `inferred_geofences` InferredGeofence[], nullable - `geometry` PolygonLocationGeometryResponse, required - `type` 'Polygon', required: Polygon Geometry type - `coordinates` array[], required: Location coordinates represented as list of list of [longitude, latitude]. - array[] - number[] - `source` 'customer_provided' | 'ht_generated', required: Source which created this location - `inclusivity` string, required: More inclusivity means more loosely defined service area - `skew` number, required: 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` number, nullable: Ratio of inferred geometry area to current geofence area (inferred/current) - `centroid_shift` number, nullable: Distance in meters between the centroid of current geofence and inferred geometry - `inferred_geofences_skew` number, nullable: 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` union: 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. - VisitDetectionConfig - `worker_handle` string, nullable: Unique customer provided identifier for a worker - `metadata_filter` object, nullable: Metadata to detect the visit based on the key value pair provided with it. - unknown - `inferred_geofence` union: Inferred geofence as per the on ground activity on places - InferredGeofence - `geometry` PolygonLocationGeometryResponse, required - `type` 'Polygon', required: Polygon Geometry type - `coordinates` array[], required: Location coordinates represented as list of list of [longitude, latitude]. - array[] - … - `source` 'customer_provided' | 'ht_generated', required: Source which created this location - `inclusivity` string, required: More inclusivity means more loosely defined service area - `skew` number, required: 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` number, nullable: Ratio of inferred geometry area to current geofence area (inferred/current) - `centroid_shift` number, nullable: Distance in meters between the centroid of current geofence and inferred geometry - unknown - `bounding_box` union: Bounding box for the location if the geometry of the place is a point - BoundingBox - `geometry` PolygonLocationGeometryResponse, required - `type` 'Polygon', required: Polygon Geometry type - `coordinates` array[], required: Location coordinates represented as list of list of [longitude, latitude]. - array[] - … - `source` 'customer_provided' | 'ht_generated', required: Source which created this location - `skew` number, required: 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` number, nullable: Ratio of bounding box area to current geofence area (bounding_box/current) - `centroid_shift` number, nullable: Distance in meters between the centroid of current geofence and bounding box - unknown - `created_by` union: Source details of who created this place - Source - `source` string, nullable: Source of the request - `timestamp` string, nullable: Time when request was made - `ip-address` string, nullable: IP address of source - `device_id` string, nullable: Id of the device that made the request - `driver_handle` string, nullable: Id of the driver who made the request - `user_id` string, nullable: Id of the user who made the request - `email` string, nullable: Email of the user who made the request - unknown - `updated_by` union: Source details of who last updated this place - Source - `source` string, nullable: Source of the request - `timestamp` string, nullable: Time when request was made - `ip-address` string, nullable: IP address of source - `device_id` string, nullable: Id of the device that made the request - `driver_handle` string, nullable: Id of the driver who made the request - `user_id` string, nullable: Id of the user who made the request - `email` string, nullable: Email of the user who made the request - unknown - `locked_from_suggestions` boolean, nullable: Whether this place is locked from receiving future suggestions - `suggestion_applied` boolean, nullable: Whether a suggestion was applied to this place - `suggestion_applied_on` string, nullable: Timestamp when a suggestion was applied to this place - `has_pending_suggestion` boolean, nullable: Whether this place has a pending suggestion - `suggestion_not_applied_reason` string, nullable: Reason why suggestion was not applied, if applicable - `suggestions_reviewed_on` string, nullable: Timestamp when suggestions were last reviewed for this place - `pagination_token` string, nullable: Identifier used to fetch the next page ## Other responses - `400`: Validation error - `401`: Authentication error --- [API](https://skmtc.dev/hypertrack/apis/hypertrack-api.md) - [All operations](https://skmtc.dev/hypertrack/apis/hypertrack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hypertrack/apis/hypertrack-api/revisions/389326c4c9c8?raw)