Geolocation Distance Filter

---
name: geolocation-distance-filter
description: When the user needs to filter locations based on proximity to a reference point within a specified radius. This skill geocodes addresses to coordinates, calculates distances between locations, and filters results based on maximum distance thresholds. Triggers include 'within X km/miles of', 'distance from', 'near location', 'proximity filter', or when location-based filtering is required for job applications, real estate, or service area analysis.
---
# Geolocation Distance Filter

## Purpose
Filter a list of items based on the geographic distance of their locations from a specified reference point. This is essential for location-based queries like finding jobs, properties, or services within a certain radius.

## Core Workflow
1.  **Identify Reference Point:** Determine the central location (e.g., "UCLA", "downtown office") and the maximum allowed distance (e.g., "within 500 km").
2.  **Geocode Reference:** Convert the reference point's address into latitude/longitude coordinates using the `google_map-maps_geocode` tool.
3.  **Extract Target Items:** Obtain the list of items to filter (e.g., from a database query). Each item must have a location field.
4.  **Geocode & Calculate:** For each candidate item:
    *   Geocode its location address.
    *   Calculate the distance from the reference coordinates using the Haversine formula (see `scripts/distance_calculator.py`).
5.  **Apply Filter:** Retain only items where the calculated distance is less than or equal to the specified maximum radius.
6.  **Return Results:** Output the filtered list and the calculated distances for context.

## Key Instructions
*   **Precision:** Always use the `google_map-maps_geocode` tool for reliable coordinate conversion. Do not assume distances.
*   **Unit Consistency:** Ensure the maximum distance threshold and the calculated distances are in the same units (kilometers by default). Convert if necessary (1 mile = 1.60934 km).
*   **Error Handling:** If geocoding fails for an item, log it and exclude it from the filtered results, noting the issue.
*   **Integration:** This filter is typically one step in a larger workflow (e.g., filter jobs, then apply other criteria like salary).

## Common Triggers
*   "Find [items] within [X] km/miles of [location]"
*   "Which [items] are closest to [reference point]?"
*   "Filter these results by distance from [address]"
*   "Show only [items] in the [area] area"
*   Implied need when location is a critical constraint (e.g., "commutable jobs", "nearby stores").

## Bundled Resources
*   `scripts/distance_calculator.py`: Contains the `calculate_distance` function for accurate distance computation.
*   `references/haversine_formula.md`: Explanation of the distance calculation method.