amap_skill

Overview

This skill integrates with the Amap (Gaode) Web Service API to perform place search, weather lookup, routing, geocoding and reverse geocoding. It requires a valid Amap Web Service API key provided via the AMAP_KEY environment variable. The skill returns structured location data and can convert between addresses and coordinates to support route planning and POI discovery.

How this skill works

The skill calls Amap REST endpoints to fetch weather (real-time or forecast), search POIs by keyword and city, compute driving routes between coordinates, and translate addresses to/from latitude-longitude. If a user supplies an address, the skill geocodes it to coordinates; if the user supplies coordinates, it reverse-geocodes to a structured address. Administrative district queries return adcodes needed for weather queries and more precise searches.

When to use it

• Check current weather or forecast for a city or administrative area.
• Search for nearby points of interest or find addresses by keyword.
• Convert an address to coordinates or find the address for given coordinates.
• Plan a driving route between two locations when you have or can obtain coordinates.
• Lookup administrative adcodes or district boundaries for precise queries.

Best practices

• Set AMAP_KEY as an environment variable before using the skill (AMAP_KEY must be a valid Amap Web Service API key).
• If you don’t know a city’s adcode, first run an administrative district query to get the adcode for weather or region-limited searches.
• For routing, prefer supplying coordinates (longitude,latitude). If a user gives an address, geocode it first to avoid ambiguous routing results.
• Limit keyword and city combinations for POI searches to reduce noisy results; use pagination if available for large result sets.
• Handle API rate limits and error responses gracefully; cache frequently requested district/adcode lookups.

Example use cases

• "What’s the weather in city X?" — fetch current weather or forecast using the city adcode.
• "Find coffee shops near Central Park" — run a POI text search scoped to the city or a coordinate radius.
• "How do I drive from A to B?" — geocode addresses to coordinates then request driving directions between coordinates.
• "What are the coordinates of 123 Main St?" — use geocoding to return longitude and latitude.
• "Which district does this coordinate belong to?" — use reverse geocoding to return the structured address and district adcode.