AgentSkillsCN

geolocation-distance-filter

当用户需要根据指定半径内与参考点的接近程度对地点进行筛选时，此技能会将地址转换为坐标，计算各地点之间的距离，并根据最大距离阈值筛选结果。触发条件包括“在X公里/英里范围内”、“距离……”、“靠近……”、“邻近筛选”，或在求职申请、房地产交易或服务区域分析中需要基于位置进行筛选时。

SKILL.md
--- frontmatter
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.