高德地图

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.
    Considers bridges, one-way streets, and road closures. Supports routes up to 500km.

Implementation Reference

• amap_mcp_server/server.py:139-197 (handler)

  The handler function decorated with @mcp.tool() that implements the maps_bicycling_by_address tool. It geocodes the origin and destination addresses, calls the coordinate-based bicycling route function, and returns the route with added address details.

  @mcp.tool()
  def maps_bicycling_by_address(origin_address: str, destination_address: str, origin_city: Optional[str] = None, destination_city: Optional[str] = None) -> Dict[str, Any]:
      """Plans a bicycle 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.
          Considers bridges, one-way streets, and road closures. Supports routes up to 500km.
      """
      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 bicycle route
          route_result = maps_bicycling_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:198-251 (helper)

  Helper function that performs the actual Amap API call for bicycling directions between coordinates, used by the address-based handler.

  @mcp.tool()
  def maps_bicycling_by_coordinates(origin_coordinates: str, destination_coordinates: str) -> Dict[str, Any]:
      """Plans a bicycle route between two coordinates.
      
      Args:
          origin_coordinates (str): Starting point coordinates in the format "longitude,latitude" (e.g. "116.434307,39.90909")
          destination_coordinates (str): Ending point coordinates in the format "longitude,latitude" (e.g. "116.434307,39.90909")
          
      Returns:
          Dict[str, Any]: Route information including distance, duration, and turn-by-turn instructions.
          Considers bridges, one-way streets, and road closures. Supports routes up to 500km.
      """
      try:
          response = requests.get(
              "https://restapi.amap.com/v4/direction/bicycling",
              params={
                  "key": AMAP_MAPS_API_KEY,
                  "origin": origin_coordinates,
                  "destination": destination_coordinates
              }
          )
          response.raise_for_status()
          data = response.json()
          
          if data.get("errcode") != 0:
              return {"error": f"Direction bicycling failed: {data.get('info') or data.get('infocode')}"}
              
          paths = []
          for path in data["data"]["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 {
              "data": {
                  "origin": data["data"]["origin"],
                  "destination": data["data"]["destination"],
                  "paths": paths
              }
          }
      except requests.exceptions.RequestException as e:
          return {"error": f"Request failed: {str(e)}"}

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

  Helper function for geocoding addresses to coordinates, used by the handler for both origin and destination.

  @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)}"}