​
引言 美客多作为拉美领先的电商平台，其开放平台提供了丰富的API接口，赋能开发者构建各类电商应用。其中，商品搜索API是获取平台商品信息的关键入口。本文将详细介绍如何调用美客多平台的关键词商品搜索API接口，包括核心概念、请求构建、响应解析以及注意事项。

1. API 基础 该API允许开发者通过发送关键词（query）来检索美客多平台上的商品列表。核心功能包括：

关键词匹配： 根据用户输入的关键词返回相关商品。
结果分页： 支持获取大量结果的分页数据。
结果排序与过滤： 提供多种排序方式（如价格、销量、相关性）和过滤条件（如分类、价格区间、卖家信息）。
返回商品核心信息： 如商品ID、标题、价格、图片链接、卖家信息、运费类型等。

1. 认证与授权 调用美客多API通常需要进行身份验证。你需要：

在美客多开发者平台注册账号并创建应用。
获取应用的 client_id 和 client_secret。
使用OAuth 2.0协议获取访问令牌 (access_token)。一个简化的令牌获取流程可能如下：
import requests

假设已获取 client_id 和 client_secret

auth_url = "https://api.mercadolibre.com/oauth/token"
payload = {
'grant_type': 'client_credentials',
'client_id': 'YOUR_CLIENT_ID',
'client_secret': 'YOUR_CLIENT_SECRET'
}
response = requests.post(auth_url, data=payload)
token_data = response.json()
access_token = token_data['access_token']

1. 构建搜索请求 获得有效的 access_token 后，即可构建搜索请求。核心端点通常是： GET /sites/MLM/search?q={keyword} (以墨西哥站点为例，MLM 为站点代码)

关键请求参数：

q (必需): 搜索关键词。例如：q=iphone
limit: 每页返回的最大结果数。
offset: 分页起始偏移量（或使用 page 参数，取决于API版本）。
sort: 排序方式。常见值有 price_asc, price_desc, relevance。
category: 分类ID，用于筛选特定类目下的商品。
price_range: 价格区间过滤，格式如 price_min-price_max。
seller_id: 特定卖家的商品。
official_store: 是否只返回官方商店商品（如 official_store=1）。
access_token: 将令牌放在请求头或作为参数传递。
示例请求 (Python):

search_url = "https://api.mercadolibre.com/sites/MLM/search"
params = {
'q': 'zapatillas deportivas', # 搜索关键词
'limit': 10, # 每页10条
'sort': 'price_asc' # 按价格升序排序
}
headers = {
'Authorization': f'Bearer {access_token}' # 推荐将token放在header
}

response = requests.get(search_url, params=params, headers=headers)
search_results = response.json()

1. 解析响应结果 成功的响应（HTTP 200）将返回一个结构化的JSON对象。主要关注点包括：

paging: 包含分页信息（总记录数 total、当前页限制 limit、当前页偏移量 offset、总页数等）。
results: 一个数组，包含匹配的商品对象列表。每个商品对象通常包含：
id: 商品唯一ID。
title: 商品标题。
price: 商品价格。
currency_id: 货币类型（如 MXN）。
available_quantity: 可用库存。
thumbnail: 商品缩略图URL。
permalink: 商品详情页URL。
seller: 卖家信息对象（包含卖家ID id、昵称 nickname 等）。
shipping: 物流信息（如是否免运费 free_shipping）。
official_store_id: 官方店铺ID（如果属于官方店）。
attributes: 商品属性列表（如品牌、颜色、尺寸等）。
filters: 可用的过滤选项（分类、价格区间等），可用于构建筛选UI。
query: 实际使用的查询词（可能经过标准化处理）。
示例结果片段解析：

假设 search_results 是API返回的JSON解析后的字典

total_results = search_results['paging']['total']
items = search_results['results']

for item in items:
print(f"商品ID: {item['id']}")
print(f"标题: {item['title']}")
print(f"价格: {item['price']} {item['currency_id']}")
print(f"图片: {item['thumbnail']}")
print(f"链接: {item['permalink']}")
print(f"卖家: {item['seller']['nickname']}")
print(f"免运费: {'是' if item['shipping']['free_shipping'] else '否'}")
print("-" * 30)

1. 分页处理 当结果总数超过 limit 时，需要通过调整 offset 或 page 参数来获取后续页面。常见策略是根据 paging 对象中的 total 和 limit 计算总页数，然后循环请求。

total_pages = (total_results + limit - 1) // limit # 计算总页数 (向上取整)
for page in range(total_pages):
params['offset'] = page * limit # 更新offset (假设API使用offset分页)
response = requests.get(search_url, params=params, headers=headers)
page_results = response.json()

# 处理当前页的结果...

1. 错误处理 务必处理可能的API错误响应。常见错误码：

401 Unauthorized: 访问令牌无效或过期。需要重新获取令牌。
403 Forbidden: 权限不足。
400 Bad Request: 请求参数错误（如缺失必需参数 q）。
429 Too Many Requests: 请求过于频繁，触发了速率限制。需要降低请求频率或实现重试机制。

1. 最佳实践与注意事项

遵守速率限制： 美客多API有严格的调用频率限制。务必查看文档并合理控制请求速率，必要时使用指数退避算法进行重试。
缓存策略： 对于非实时性要求极高的场景（如展示热门商品），可以考虑缓存结果以减少API调用。
处理特殊字符： 对关键词进行必要的URL编码。
关注API版本： 美客多API可能更新，留意官方文档的变更通知。
结果去重： 同一个商品可能出现在多个搜索结果中，应用层可能需要处理。
数据新鲜度： API返回的数据可能存在延迟，对于实时库存、价格变动敏感的应用，需结合其他API（如商品详情API）或考虑数据新鲜度要求。
结语 美客多的关键词商品搜索API是连接平台海量商品数据的强大工具。通过理解认证流程、掌握请求参数、正确解析响应并处理好分页与错误，开发者可以高效地利用此API构建商品比价工具、选品分析、市场调研、个性化推荐等各类应用。务必参考最新的官方文档以获取最准确的信息。

延伸阅读

美客多开发者中心
OAuth 2.0 授权文档
商品搜索API详细文档
希望这篇技术分享能帮助你快速上手美客多的商品搜索API！

​