高德地图

Instructions

Args:
    origin_address (str): Starting point address (e.g. "北京市朝阳区阜通东大街6号")
    destination_address (str): Ending point address (e.g. "北京市海淀区上地十街10号")
    origin_city (Optional[str]): Optional city name for the origin address to improve geocoding accuracy
    destination_city (Optional[str]): Optional city name for the destination address to improve geocoding accuracy
    
Returns:
    Dict[str, Any]: Route information including distance, duration, and turn-by-turn instructions.
    Supports routes up to 100km.

Implementation Reference

• amap_mcp_server/server.py:252-309 (handler)

  Main handler for maps_direction_walking_by_address tool. Geocodes input addresses to coordinates using maps_geo helper, then delegates to maps_direction_walking_by_coordinates for the actual walking route planning via Amap API. Includes input validation, error handling, and enriches output with original addresses.

  @mcp.tool()
  def maps_direction_walking_by_address(origin_address: str, destination_address: str, origin_city: Optional[str] = None, destination_city: Optional[str] = None) -> Dict[str, Any]:
      """Plans a walking route between two locations using addresses. Unless you have a specific reason to use coordinates, it's recommended to use this tool.
      
      Args:
          origin_address (str): Starting point address (e.g. "北京市朝阳区阜通东大街6号")
          destination_address (str): Ending point address (e.g. "北京市海淀区上地十街10号")
          origin_city (Optional[str]): Optional city name for the origin address to improve geocoding accuracy
          destination_city (Optional[str]): Optional city name for the destination address to improve geocoding accuracy
          
      Returns:
          Dict[str, Any]: Route information including distance, duration, and turn-by-turn instructions.
          Supports routes up to 100km.
      """
      try:
          # Convert origin address to coordinates
          origin_result = maps_geo(origin_address, origin_city)
          if "error" in origin_result:
              return {"error": f"Failed to geocode origin address: {origin_result['error']}"}
          
          if not origin_result.get("return") or not origin_result["return"]:
              return {"error": "No geocoding results found for origin address"}
          
          origin_location = origin_result["return"][0].get("location")
          if not origin_location:
              return {"error": "Could not extract coordinates from origin geocoding result"}
          
          # Convert destination address to coordinates
          destination_result = maps_geo(destination_address, destination_city)
          if "error" in destination_result:
              return {"error": f"Failed to geocode destination address: {destination_result['error']}"}
          
          if not destination_result.get("return") or not destination_result["return"]:
              return {"error": "No geocoding results found for destination address"}
          
          destination_location = destination_result["return"][0].get("location")
          if not destination_location:
              return {"error": "Could not extract coordinates from destination geocoding result"}
          
          # Use the coordinates to plan the walking route
          route_result = maps_direction_walking_by_coordinates(origin_location, destination_location)
          
          # Add address information to the result
          if "error" not in route_result:
              route_result["addresses"] = {
                  "origin": {
                      "address": origin_address,
                      "coordinates": origin_location
                  },
                  "destination": {
                      "address": destination_address,
                      "coordinates": destination_location
                  }
              }
          
          return route_result
      except Exception as e:
          return {"error": f"Route planning failed: {str(e)}"}

• amap_mcp_server/server.py:311-362 (helper)

  Core helper function implementing the walking directions API call to Amap. Takes coordinates, fetches route data, parses paths and steps into a structured format with instructions, distances, etc. Called by the main handler after geocoding.

  @mcp.tool()
  def maps_direction_walking_by_coordinates(origin: str, destination: str) -> Dict[str, Any]:
      """步行路径规划 API 可以根据输入起点终点经纬度坐标规划100km 以内的步行通勤方案，并且返回通勤方案的数据
      
      Args:
          origin (str): 起点经纬度坐标，格式为"经度,纬度" (例如："116.434307,39.90909")
          destination (str): 终点经纬度坐标，格式为"经度,纬度" (例如："116.434307,39.90909")
          
      Returns:
          Dict[str, Any]: 包含距离、时长和详细导航信息的路线数据
      """
      try:
          response = requests.get(
              "https://restapi.amap.com/v3/direction/walking",
              params={
                  "key": AMAP_MAPS_API_KEY,
                  "origin": origin,
                  "destination": destination
              }
          )
          response.raise_for_status()
          data = response.json()
          
          if data["status"] != "1":
              return {"error": f"Direction Walking failed: {data.get('info') or data.get('infocode')}"}
              
          paths = []
          for path in data["route"]["paths"]:
              steps = []
              for step in path["steps"]:
                  steps.append({
                      "instruction": step.get("instruction"),
                      "road": step.get("road"),
                      "distance": step.get("distance"),
                      "orientation": step.get("orientation"),
                      "duration": step.get("duration")
                  })
              paths.append({
                  "distance": path.get("distance"),
                  "duration": path.get("duration"),
                  "steps": steps
              })
              
          return {
              "route": {
                  "origin": data["route"]["origin"],
                  "destination": data["route"]["destination"],
                  "paths": paths
              }
          }
      except requests.exceptions.RequestException as e:
          return {"error": f"Request failed: {str(e)}"}

• amap_mcp_server/server.py:44-82 (helper)

  Geocoding helper used by the main handler to convert addresses to coordinates ("location" field). Essential for address-based routing.

  @mcp.tool()
  def maps_geo(address: str, city: Optional[str] = None) -> Dict[str, Any]:
      """将详细的结构化地址转换为经纬度坐标。支持对地标性名胜景区、建筑物名称解析为经纬度坐标"""
      try:
          params = {
              "key": AMAP_MAPS_API_KEY,
              "address": address
          }
          if city:
              params["city"] = city
              
          response = requests.get(
              "https://restapi.amap.com/v3/geocode/geo",
              params=params
          )
          response.raise_for_status()
          data = response.json()
          
          if data["status"] != "1":
              return {"error": f"Geocoding failed: {data.get('info') or data.get('infocode')}"}
              
          geocodes = data.get("geocodes", [])
          results = []
          for geo in geocodes:
              results.append({
                  "country": geo.get("country"),
                  "province": geo.get("province"),
                  "city": geo.get("city"),
                  "citycode": geo.get("citycode"),
                  "district": geo.get("district"),
                  "street": geo.get("street"),
                  "number": geo.get("number"),
                  "adcode": geo.get("adcode"),
                  "location": geo.get("location"),
                  "level": geo.get("level")
              })
          return {"return": results}
      except requests.exceptions.RequestException as e:
          return {"error": f"Request failed: {str(e)}"}