--- title: "Get all nearby workers" method: POST path: "/nearby/v4" tags: ["Nearby"] --- # Get all nearby workers `POST /nearby/v4` ## Request - Base URL: `https://v3.api.hypertrack.com` - URL: `https://v3.api.hypertrack.com/nearby/v4` - Auth: one of: - HTTP basic - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Use this API to get all the nearby workers from order destination. A maximum of 1000 workers are returned in order of their haversine distance from order destination. Note: if the search_radius filter is not specified, it uses the maximum allowed search radius of 100 miles (160934 meters). ## Request body - NearbyRequest - `ops_group_handle` string, nullable: ops group handle used to filter nearby search results by operational group - `order` NearbyOrder, required - `destination` union: Destination location around which to search workers. - NearbyDestination - `geometry` union: Destination geometry, As of right now, only 'Point' is supported. - LocationGeometry - `type` 'Point', required: Geometry type - `coordinates` number[], required: Location coordinates represented as [longitude, latitude] - unknown - `place_handle` string, nullable: Optional place handle used to search nearby workers for. `geometry` will be derived from place handle and should not provided with this parameter. - unknown - `order_handle` string, nullable: Optional order handle used to search nearby workers for, this can later be used for tracking and associate nearby requests with corresponding orders - `metadata` object, nullable: Optional order metadata. - `search_type` 'eta' | 'region', required - `search_filter` union - SearchFilter - `include_on_route` boolean, nullable: True when on route workers are also needed as part of response (default value is false). - `worker_profile` object, nullable: Used to specify a filter that is applied on the workers returned in a nearby search result; For example, this profile filter can represent attributes describing your gig workers, such as a team assignment, gig category, etc. - `worker_list` string[], nullable: Array of worker handles whose estimates to order destination will be calculated. Only for search type 'eta', if present only `search_radius` filter is allowed, others are not allowed. - `work_status` union: Optional filter to specify the work status of workers to include in the search results. - WorkStatus - `tracking` boolean, nullable: Indicates if the worker is currently being tracked. - `available` boolean, nullable: Indicates if the worker is available for new tasks. - unknown - `search_radius` integer, nullable: Maximum distance (haversine) in meters of workers from order destination, maximum of 160934 meters (100 miles). - unknown - `limit` integer, nullable ## Response `200` Successful response - NearbyResponse - `request_id` string, required: Unique identifier for the nearby request. - `workers` NearbyWorker[], required: List of worker objects. - `device` NearbyDevice, required - `device_id` string, required: Device id of the device. - `info` union: device_info. Same fields support as in devices API. - NearbyDeviceInfo - `timezone` string, nullable: The timezone on the device in TZ format. - `os_name` string, nullable: The operating system of the device, can be one of iOS or Android. - `device_brand` string, nullable: The brand of the device. - `sdk_version` string, nullable: The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native. - `device_model` string, nullable: The device model. - `network_operator` string, nullable: The network operator for the device. - `os_version` string, nullable: The version of the operating system on the device. - `os_hardware_identifier` string, nullable: Hardware identifier returned from the OS. (OS specific. Android uses ANDROID_ID; iOS uses identifierForVendor. - `name` string, nullable: Name of the device. - unknown - `profile` object, nullable: Device metadata submitted via Mobile SDKs (Android, iOS) or Devices API. - `status` union: Device status. - NearbyDeviceStatus - `value` string, required: Can be one of active, inactive, disconnected, available or unavailable. Please read here to understand how HyperTrack tracks device status. - `data` NearbyDeviceStatusData, required - `recorded_at` string, nullable: ISO 8601 date when the device status was recorded. - `activity` string, nullable: Device activity (optional). If available, can be one of stop, walk, or drive. - `reason` string, nullable: For inactive devices only. Can be one of: location_permissions_denied, location_services_disabled, motion_activity_permissions_denied, motion_activity_services_disabled, motion_activity_services_unavailable, tracking_stopped, tracking_service_terminated, uninstalled. - unknown - `location` PointLocationGeometry, required - `type` 'Point', required: Point Geometry type - `coordinates` number[], required: Location coordinates represented as [longitude, latitude]. - `worker_handle` string, nullable: Unique customer provided identifier for a worker - `name` string, nullable: Name of the worker - `ops_group_handle` string, nullable: Unique identifier for an Ops Group to which the worker belongs - `product_types` string[], nullable: List of product types used for worker matching during order planning - `profile` object, nullable: Metadata associated with a worker - `work_status` union: work_status of the worker with respect to availability and on order fulfilment - DriverStatus1 - `tracking` boolean, required: Flag indicating whether the worker is currently on work - `available` boolean, required: Flag indicating if the worker is available for work - unknown - `schedule` union[], nullable: List indicating the schedule of a worker for work assignment - union - DriverDateSchedule - `start_time` string, required: Start time represented by HH:mm of the worker's day schedule - `end_time` string, required: End time represented by HH:mm of the worker's day schedule - `date` string, required: Date on which the worker is available for work - `ops_group_handle` string, nullable: Unique identifier for an Ops Group - `priority` integer, nullable: Priority of schedule of a worker - DriverRecurringSchedule - `start_time` string, required: Start time represented by HH:mm of the worker's day schedule - `end_time` string, required: End time represented by HH:mm of the worker's day schedule - `day_of_week` 'SUNDAY' | 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY', required: Day of the week when the worker is available for work - `ops_group_handle` string, nullable: Unique identifier for an Ops Group - `priority` integer, nullable: Priority of schedule of a worker - `created_at` string, nullable: Timestamp at which the worker was created - `home` union: Worker home - LocationWithoutRadiusResponse - `address` string, nullable: Address for the location - `geometry` LocationGeometryResponse, required - `type` string, required: Geometry type - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude]. - unknown - unknown - `unavailable_on` string[], nullable: List of dates (YYYY-MM-DD) on which the worker is not available - `location_permission` union: Last known location permission on the worker's device - LocationPermission1 - `state` 'always' | 'foreground_only' | 'never' | 'location_imprecise' | 'unknown', required: State of location permission - `recorded_at` string, nullable: Time stamp of the last known location permission - unknown - `battery` union: Information of the battery status. - BatteryStatus1 - `battery_percent` integer, required: Integer indicating the percent of charge on the battery. - `recorded_at` string, required: Timestamp of the reading - unknown - `timezone` string, nullable: Timezone of the worker - `duration` number, nullable: Time needed to reach the nearest location in seconds; null if no location was found, only for eta search_type. - `distance` number, nullable: Distance of the nearest location from the requested location in meters; null if no location was found. For eta search_type its the actual drive distance, for region search_type its the haversine distance. - `ongoing_route` union: Ongoing route summary (only present if workers has any ongoing route and request has include_on_route as true). - NearbyOngoingRoute - `route_handle` string, required: route handle which is still ongoing (only present if worker has any ongoing route and request has include_on_route as true). - `destination` object, required: Destination geometry for Ongoing route (only present if workers has any ongoing route and request has include_on_route as true). - `remaining_distance` integer, required: Distance (in meters) workers needs to travel to reach route destination (only present if workers has any ongoing route and request has include_on_route as true). - `remaining_duration` integer, required: Time (in seconds) needed for workers to travel to reach route destination (only present if workers has any ongoing route and request has include_on_route as true). - unknown - `summary` NearbySummary, required - `total_workers` integer, required: Number of matching workers found near the order destination, up to the API's maximum of 1000. This can be higher than the number of workers returned in the response. - `processed_workers` integer, required: Number of workers processed and returned in workers response. - `unprocessed_workers` integer, required: Number of workers that have not been processed. - `outside_region_workers` integer, required: Number of workers outside nearby region (default value of search_filter.search_radius), only returned if worker_list filter is specified. - `no_route_workers` integer, required: Number of workers for whom no route was found to the destination, only returned if worker_list filter is specified. ## Other responses - `400`: Bad Request - `401`: Authentication error - `404`: Not Found - `500`: Internal Server 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)