--- title: "Get all nearby searches performed" method: GET path: "/nearby/v4" tags: ["Nearby"] --- # Get all nearby searches performed `GET /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) This API returns a list of all nearby searches performed. The response includes the search parameters, the results of the search. The API is useful for tracking the history of nearby searches and for debugging purposes. The API returns a paginated list of nearby searches, with the ability to filter by date range and search parameters. ## Query parameters - `pagination_token` string, nullable - `request_id` string, nullable - `search_type` 'eta' | 'region' | 'null', nullable - `order_handle` string, nullable - `place_handle` string, nullable - `from_date` string, nullable - `to_date` string, nullable - `limit` integer, nullable - `aggregate` boolean, nullable ## Response `200` Successful response - NearbySearchListResponse - `requests` NearbySearchRequestSummary[], required: List of nearby searches performed. - `request_id` string, required: Unique identifier for the nearby search request. - `request` NearbyRequest, required - `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. - … - `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 - … - 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 - `created_on` string, required: Timestamp at which the nearby search request was created. This is in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). - `workers` NearbyWorkerSummary[], nullable: Nearby search response. - `device_id` string, required: Device id of the worker. - `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 - `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 - `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. - `duration` number, nullable: Time needed to reach the nearest location in seconds; null if no location was found, only for eta search_type. - `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` union: Summary of the nearby search results. - NearbySummary - `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. - unknown - `timezone` string, nullable: Timezone of the worker - `pagination_token` string, nullable: Token to be used for pagination. If present, it indicates that there are more pages of results available. - `aggregates` union: Aggregates for nearby search requests. This is only present when the request is made with aggregate=true. - NearbyAggregates - `total_requests` integer, required: Total number of nearby search requests performed. This is only present when the request is made with aggregate=true. - `avg_workers_per_request` number, required: Average number of workers returned per nearby search request. This is only present when the request is made with aggregate=true. - `unique_workers` integer, required: Total number of unique workers returned across all nearby search requests. This is only present when the request is made with aggregate=true. - `request_with_workers` integer, required: Total number of nearby search requests that returned at least one worker. This is only present when the request is made with aggregate=true. - unknown ## 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)