概述

Mapfolio API 通过 RESTful 接口提供对瑞士公司数据的编程访问。所有端点都使用 OpenAPI 3.0 规范进行文档化，确保一致性和易于集成。

开始使用

身份验证

Mapfolio API 使用 API 密钥身份验证。您可以从账户设置获取您的 API 密钥。

API 密钥标头：

X-API-Key: mapf_your_api_key_here

Bearer 令牌（替代方案）：

Authorization: Bearer mapf_your_api_key_here

基础 URL

所有 API 请求应发送到：

https://mapfolio.app

速率限制

API 请求受到速率限制以确保公平使用：

已认证请求：每个 API 密钥每小时 1000 个请求
未认证请求：每个 IP 地址每小时 10 个请求

速率限制信息包含在响应标头中：

X-RateLimit-Limit：允许的最大请求数
X-RateLimit-Remaining：当前窗口中的剩余请求数
X-RateLimit-Reset：限制重置时的 Unix 时间戳

可用端点

公司搜索

使用高级过滤选项搜索公司：

在公司名称中进行文本搜索
按州（瑞士州）过滤
按公司状态过滤
支持分页

公司详情

检索特定公司的详细信息：

公司资料数据
位置信息
法律状态
注册详情

统计信息

访问有关瑞士公司的聚合统计信息：

公司总数
州级统计
基于字母的分布
两个字母组合的计数

自动完成

获取以下内容的自动完成建议：

公司名称
城市
邮政编码

随机公司

检索随机公司样本用于测试和探索。

响应格式

所有成功的 API 响应都遵循一致的结构：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

错误响应包含详细信息：

{
  "error": "错误消息",
  "details": "其他错误详情"
}

错误代码

400 Bad Request：无效的请求参数
401 Unauthorized：缺少或无效的 API 密钥
403 Forbidden：权限不足
404 Not Found：未找到资源
429 Too Many Requests：超过速率限制
500 Internal Server Error：服务器错误

OpenAPI 规范

完整的 OpenAPI 3.0 规范可在以下位置获得：

交互式文档：/api-docs.html
OpenAPI JSON：/api/docs/openapi.json

您可以将 OpenAPI 规范与任何兼容的工具一起使用：

Swagger UI
Postman
Insomnia
客户端库的代码生成器

代码示例

cURL

curl -H "X-API-Key: mapf_your_api_key_here" \
  https://mapfolio.app/api/search?q=technology

JavaScript (Fetch)

const response = await fetch('https://mapfolio.app/api/search?q=technology', {
  headers: {
    'X-API-Key': 'mapf_your_api_key_here'
  }
})
const data = await response.json()

Python (Requests)

import requests

headers = {'X-API-Key': 'mapf_your_api_key_here'}
response = requests.get(
  'https://mapfolio.app/api/search',
  params={'q': 'technology'},
  headers=headers
)
data = response.json()

支持

有关 API 支持和问题：

文档：访问交互式 API 文档
电子邮件：support@mapfolio.app
问题：通过您的账户仪表板报告问题

使用条款

使用 Mapfolio API，即表示您同意我们的服务条款和隐私政策。请查看速率限制和使用指南以确保合规性。