下面以获取天气预报的功能为例，介绍如何调用API，完善工具的实际功能。

实时天气代码

import requests
import os
from typing import Dict        # 必须添加类型注解
import dotenv  

dotenv.load_dotenv()

def check_weather(location: str) -> str:
    '''
    Return the weather forecast for the specified location via 高德地图天气API.
    Args:
        location: 城市名称（如"杭州"、"北京"）
    Returns:
        格式化的天气信息字符串，失败时返回友好提示
    '''
    # 1. 从环境变量读取API Key（避免硬编码）
    api_key = os.getenv("AMAP_WEATHER_API_KEY")
    if not api_key:
        return "Error: 未配置高德天气API Key（请设置环境变量 AMAP_WEATHER_API_KEY）"
    
    # 2. 高德天气API配置（实时天气接口）
    base_url = "https://restapi.amap.com/v3/weather/weatherInfo"
    params: Dict[str, str] = {
        "key": api_key,          # API Key
        "city": location,        # 城市名称
        "extensions": "base",    # base=实时天气，all=预报天气
        "output": "json"         # 返回格式
    }
    try:
        # 3. 发送API请求（设置超时，避免挂起）
        response = requests.get(
            base_url,
            params=params,
            timeout=10  # 超时时间10秒
        )
        response.raise_for_status()  # 触发HTTP错误（如403/500）
        
        # 4. 解析响应数据
        result = response.json()
        if result.get("status") != "1":
            return f"Error: 高德API返回错误 - {result.get('info', '未知错误')}"
        
        # 提取天气数据（取第一个城市的第一条记录）
        weather_data = result.get("lives", [])
        if not weather_data:
            return f"Error: 未查询到{location}的天气信息"
        
        live = weather_data[0]
        city = live.get("city", "未知")
        weather = live.get("weather", "未知")
        temperature = live.get("temperature", "未知")
        wind_dir = live.get("winddirection", "未知")
        wind_power = live.get("windpower", "未知")
        report_time = live.get("reporttime","未知")
        
        # 5. 格式化返回结果
        return (
            f"{city}实时天气：\n"
            f"天气：{weather}\n"
            f"温度：{temperature}℃\n"
            f"风向：{wind_dir}\n"
            f"风力：{wind_power}级\n"
            f"report_time: {report_time}"
        )
    
    except requests.exceptions.Timeout:
        return f"Error: 调用高德API超时（{location}）"
    except requests.exceptions.RequestException as e:
        return f"Error: 调用高德API失败 - {str(e)}"
    except Exception as e:
        return f"Error: 解析天气数据失败 - {str(e)}"

# ---------------------- 测试代码 ----------------------
if __name__ == "__main__":
    print(check_weather("杭州"))

API详细介绍        

        API（Application Programming Interface，应用程序编程接口） 是一套预先定义的规则、协议和工具，用于不同软件系统之间进行通信、数据交换和功能调用，而无需了解对方的内部实现。它就像餐厅的服务员：接收你的请求（点单）、传递给后厨（系统）、再将结果（菜品）返回给你。

工作机制

         API 通常基于 客户端-服务器模型，通过 HTTP/HTTPS 协议进行交互：

• 请求（Request）：由客户端发起，包含 端点（Endpoint）、请求方法（Method）（如 GET、POST、PUT、DELETE）、以及参数（Params）或请求体（Request Body)。

• 响应（Response）：由服务器返回，包含 状态码（如 200 OK、404 Not Found）、以及数据内容（常用 JSON 格式）。

端点

        端点就是代码中的base_url，是 API 的具体访问地址，相当于 “服务器上的功能门牌号”。每个 端点对应一个具体功能：高德的天气端点专门处理天气查询，比如它的另一个端点（如/v3/geocode/geo）则处理地理编码（地址转经纬度）。

请求方法

方法	作用	你的代码中的应用
GET	从服务器获取数据（只读，无副作用）	request.get(): 向高德服务器 “获取” 天气数据，是最常用的查询类 API 方法
POST	向服务器提交 / 创建数据（如提交表单、上传文件）	比如用户注册 API，用 POST 提交用户名 / 密码
PUT	全量更新服务器数据（如修改用户全部信息）	比如修改用户手机号，用 PUT 提交新手机号
DELETE	删除服务器数据（如删除订单）	比如删除已创建的收藏地址

参数 / 请求体

        参数和请求体都是客户端发给服务器的具体需求信息，告诉服务器 “要查什么、要操作什么”，分两种形式：

• 参数（Params）：主要配合GET方法使用，拼在端点后。
• 请求体（Request Body）：主要配合POST/PUT方法使用，参数放在请求的 “正文” 中（而非 URL），更适合传输大量 / 敏感数据（如 JSON 格式的表单数据）。
• 核心区别：Params 是 URL 的一部分（可见），请求体是独立的（不可见），安全性更高。

状态码

状态码范围	含义	示例 & 代码中的处理
2xx	成功	200 OK：请求成功，服务器返回数据
4xx	客户端错误	403 Forbidden：API Key 错误 / 无权限；404 Not Found：Endpoint 错误（如输错路径）
5xx	服务器错误	500 Internal Server Error：服务器内部故障，无法处理请求

数据内容

        数据内容是服务器返回的具体结果，JSON 是最常用的格式。

        JSON：JavaScript 对象表示法（JavaScript Object Notation），是一种轻量级的数据格式，易读，易解析，具体的返回格式一定要看API介绍

requests库

        Python requests是一个常用的 HTTP 请求库，可以方便地向网站发送 HTTP 请求，并获取响应结果。

方法	描述
delete(url, args)	发送 DELETE 请求到指定 url
get(url, params, args)	发送 GET 请求到指定 url
head(url, args)	发送 HEAD 请求到指定 url
patch(url, data, args)	发送 PATCH 请求到指定 url
post(url, data, json, args)	发送 POST 请求到指定 url
put(url, data, args)	发送 PUT 请求到指定 url
request(method, url, args)	向指定的 url 发送指定的请求方法

API Key

        API Key是平台给你的唯一身份凭证。

创建API Key

         API使用的是高德地图网络服务API（高德开放平台 | 高德地图API），通过链接登录高德开放平台，进入右上角的控制台，在左边菜单栏中选中应用管理-我的应用，然后创建应用-添加key。

获取API Key

        在项目根目录中创建一个.env文件，添加AMAP_WEATHER_API_KEY=your_key。

        Python-dotenv 是一个用于管理环境变量的工具，可以从.env 文件中读取键值对并将其加载为环境变量。在 Python 项目中，可以通过load_dotenv()方法加载.env文件，然后通过os.getenv()获取指定的环境变量：

from dotenv import load_dotenv
import os
# 自动加载 .env 文件
load_dotenv()
# 获取环境变量
api_key = os.getenv("AMAP_WEATHER_API_KEY")

解析响应数据

        requests.get()返回的原始响应是字节流，格式由 API 决定。代码在params中指定了output格式是为json。

        实时天气的响应数据格式如下所示：天气查询-高级 API 文档-开发指南-Web服务 API | 高德地图API

名称			含义	规则说明
status			返回状态	值为0或1 1：成功；0：失败
count			返回结果总数目
info			返回的状态信息
infocode			返回状态说明,10000代表正确
lives			实况天气数据信息
	province		省份名
	city		城市名
	adcode		区域编码
	weather		天气现象（汉字描述）
	temperature		实时气温，单位：摄氏度
	winddirection		风向描述
	windpower		风力级别，单位：级
	humidity		空气湿度
	reporttime		数据发布的时间
forecasts（省略）

        response.json()会把 JSON 字符串解析成对应的 Python 数据结构：

JSON 格式	转换后的 Python 类型
JSON 对象 { }	Python 字典
JSON 数组 [ ]	Python 列表
嵌套 JSON	字典 + 列表嵌套