美客多平台关键词商品搜索API接口实践指南-平芜编程栈

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

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

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

2. 认证与授权调用美客多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']

3. 构建搜索请求获得有效的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()

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

paging: 包含分页信息（总记录数total、当前页限制limit、当前页偏移量offset、总页数等）。
results: 一个数组，包含匹配的商品对象列表。每个商品对象通常包含：
- id: 商品唯一ID。
- title: 商品标题。
- price: 商品价格。
- currency_id: 货币类型（如MXN）。
- available_quantity: 可用库存。
- thumbnail: 商品缩略图URL。
- permalink: 商品详情页URL。
- seller: 卖家信息对象（包含卖家IDid、昵称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)

5. 分页处理当结果总数超过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() # 处理当前页的结果...

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