跳转到主要内容
CarbonMeld CarbonMeld 碳观测站
高级版

CarbonMeld API(v1)

更新日期:

高级版包含 REST API v1:项目记录、筛选列表与市场统计。使用 Bearer 密钥,默认每个密钥每天 300 次请求。

打开账户页面 · 高级版详情与价格

API 返回哪些数据

读取 CarbonMeld 持有的项目数据:项目列表、市场统计,以及包含已有评级和文档分析的单个项目记录。若有高级版详情,项目接口会将其与公开数据合并。评级和分析取决于已发布的记录;高级版不会生成尚不存在的分析。

评级方法论

获取密钥

拥有有效的高级版访问权限时,在账户页面登录后生成 API 密钥。密钥只显示一次,请立即保存。重新生成会撤销旧密钥。高级版访问权限结束后密钥无法通过认证;重新获得访问权限后,未被撤销的密钥可再次使用。

打开账户页面

身份认证

每次请求都需在 Authorization 请求头中发送密钥。密钥以 cmk_ 开头,后接64个小写十六进制字符。示例使用占位符:请在本地替换为您自己的密钥,并妥善保管。应用程序也可以改用您的 CarbonMeld 账户登录(OAuth 2.1,使用 PKCE,权限范围 carbonmeld.read),并以同样方式发送获得的访问令牌。

Authorization: Bearer cmk_YOUR_KEY_HERE

本 API 的机器可读说明(OpenAPI 3.1): https://carbonmeld.com/api/v1/openapi.json

接口

API 的全部请求。注明 MCP 工具的行,其请求与该工具返回相同的对象;每个请求的参数和返回内容见 OpenAPI 说明。

请求返回内容
GET /api/v1/stats当前导出数据中的市场统计,包括项目数、登记处数和 updated_at。这是已收录项目数量,不是已完成评估的数量。
GET /api/v1/projects筛选后的项目列表:updated_at、total(筛选后的总数)、limit、offset 和 projects。
GET /api/v1/projects/<id_or_slug>通过登记编号、规范 slug 或别名获取单个项目。返回已有高级版详情时,会计入共享的每日项目额度。
POST /api/v1/projects/batch一次调用获取多个项目记录:每个 id 返回与 get_project 相同的记录,按所给顺序排列;某个 id 失败时给出该 id 自己的错误。每返回一条记录即占用共享项目额度,与 get_project 完全相同。超出单次调用请求上限的 id 会以可重试状态返回且未被打开(不占用额度):请对这些 id 重新发起请求。与此 MCP 工具返回相同的对象: get_projects
GET /api/v1/projects/<id_or_slug>/page按页面所示,返回项目页面在记录之外给出的内容:页面上的提示、“本分析是如何完成的”、相似项目、PDF 报告的地址,以及该项目在各排行榜中的位置。
GET /api/v1/projects/<id_or_slug>/ranks按项目页面所示,返回该项目在各排行榜中的位置。
GET /api/v1/methodologies/<code>按 CarbonMeld 方法学页面的内容返回一个方法学:附来源的身份卡;方法论 v3 如何解读此类项目(在 v3 中不变的 v2.2 规则、已更改的规则及其变成的 v3 规则,以及指向 v2.2 原有规则的链接);版本历史和过渡;其项目(v3 评级的排名或列表);页面链接。与此 MCP 工具返回相同的对象: get_methodology
GET /api/v1/standards/<code>按 CarbonMeld 标准页面的内容返回一个标准:附来源的身份卡;方法论 v3 如何解读此标准的项目(在 v3 中不变的 v2.2 碳信用机制规则、已更改的规则及其变成的 v3 规则,以及指向 v2.2 原有规则的链接);其发布的方法学和其项目所用的方法学;其项目(v3 评级的排名或列表);页面链接。与此 MCP 工具返回相同的对象: get_standard
GET /api/v1/rankings/<dimension>[/<value>]按网站所示返回排行榜:某一维度的各个榜单及其数量和平均分,或某个榜单中按评分排序的项目(至少5个已评分),并附页面链接。领域榜单按项目被评分时所属的领域分组。与此 MCP 工具返回相同的对象: get_ranking
GET /api/v1/developers/<slug>按 CarbonMeld 开发商页面的内容返回一个项目开发商:项目数、具有方法论 v3 评级的项目数和登记状态为被拒绝、已撤回、已终止、暂停或签发被拒的项目数、其标准和国家,以及按页面顺序排列的项目,每个项目附登记编号、国家、登记状态、评级或分析状态以及项目链接;评级按列表所示:方法论 v3 的评级及其区间、标注为 v2.2 的 v2.2 评分,或“评级为时尚早”/“暂无法评估”/“尚无适用的公开评定”/“暂不显示评级”,重新评估期间标为暂定。并附页面链接。没有公司层面的评级;名称有歧义时需进一步确认。与此 MCP 工具返回相同的对象: get_developer
GET /api/v1/buyers/<slug>按 CarbonMeld 页面所示返回组织的公开注销记录:吨数、注销次数、所注销项目的质量、其项目(每个项目附注销吨数和项目当前的评分)以及最近的注销。注销受益方不一定是购买方;名称有歧义时需进一步确认。与此 MCP 工具返回相同的对象: get_buyer
GET /api/v1/ccp-tracker按网站所示返回 ICVCM CCP 追踪表:诚信委员会对方法学的评估及其状态和各状态的数量,以及每项评估中 CarbonMeld 以相同方法学代码追踪的该碳信用机制的项目数量(涵盖所有版本,并非 CCP 标签信用的数量)及其排行榜,并附表格来源和获取日期。与此 MCP 工具返回相同的对象: ccp_tracker
GET /api/v1/corsia按网站所示,按登记处和阶段返回 CORSIA 登记处标签,以及评分最高的第一阶段项目和各登记处的平均评分,均取自项目当前的评分。余额为所有年份的未注销单位,并非符合 CORSIA 资格的单位。与此 MCP 工具返回相同的对象: corsia_supply
GET /api/v1/claims-changes返回 CarbonMeld 记录的最近30天的变化:规则制定机构的官方通知(ICVCM、Verra、Gold Standard、SBTi 等;发布机构、标题、链接、日期)以及项目的登记处标签的新增或移除(附各项目页面链接),以及整个窗口内每类标签变化涉及的项目数量。与此 MCP 工具返回相同的对象: what_changed
GET /api/v1/method按 /methodology/ 页面所示返回 CarbonMeld 的评级方法:方法论 v3,基于文件的评级。不带参数时:页面的各部分、方法论版本、四个维度及其权重,以及已存档的 v2.2 规则的地址。某一部分:页面上的文字,附其中的规则编号,每张规则卡片一行。按编号(A-START、Q-FNRB-ABOVE)或规则卡片的键返回一条规则:名称、作用、每项效果及其幅度、适用起始时间、来源及来源原文。v2.2 的编号(CM-…)返回该规则在 v2.2 中的内容及其在 v3 中的情况:不变、已更改(附其变成的 v3 规则)或已删除。某一维度(additionality、quantification、permanence、claim_safety、overall):作用于该维度的规则,分页返回(limit、offset;还有更多时给出 next_offset)。方法论 v3 没有 criterion。与此 MCP 工具返回相同的对象: get_method
GET /api/v1/articles按网站文章索引所示搜索 CarbonMeld 的英文、中文或日文文章:按词语(每个词语都须出现在标题、摘要或主题中)、按主题(网站该主题页面上的文章)和按日期。返回匹配总数和其中一页结果,按从新到旧或从旧到新排序(还有更多时给出 next_offset):标题、日期、摘要、主题、分类和链接。没有匹配时返回空列表,而不是错误。与此 MCP 工具返回相同的对象: search_articles
GET /api/v1/portfolio按页面所示返回您自己的投资组合(我的投资组合):您保存的项目,每个项目附其评级(按列表所示:方法论 v3 的评级及其区间、标注为 v2.2 的 v2.2 评分,或“评级为时尚早”/“暂无法评估”/“尚无适用的公开评定”/“暂不显示评级”;重新评估期间标为暂定)、分析状态、登记状态、年份、在售数量和分析日期;按方法论 v3 读取的项目附其负面事实,保留 v2.2 评分的项目附其风险标志,并标注 v2.2;仅当所有已评级项目属于同一方法论版本时才给出各维度的数值;v3 评级的平均值;两个分开计算的数:按方法论 v3 读取的项目的负面事实总数和保留 v2.2 评分项目的风险标志总数;本周剩余修改次数;以及这些项目最近 30 天的变更提醒。仅限读取:保存和移除项目需在网站上进行。不占用每日项目额度。与此 MCP 工具返回相同的对象: my_portfolio
POST /api/v1/check-offer将粘贴的报价文本与记录中的登记、年份、数量、声明和开发商信息比较,不确认特定序列号的所有权或可用性。与此 MCP 工具返回相同的对象: check_offer
POST /api/v1/mcp面向 AI 助手的 MCP 服务器(通过 HTTP POST 使用 JSON-RPC 2.0)。MCP 指南

项目列表参数

参数允许值
registry数据中存在的标准代码,不区分大小写(例如 VCS)。未知值返回400,并列出可用值。
min_score0至10之间的数值。只要提供此参数,即使为0,也会排除没有数值评分的项目;省略该参数可包含未评分项目。
q必须全部出现在项目名称、登记编号、国家、方法学或领域中的词语(最多100个字符)。
countryISO 3166-1 两位字母代码(例如 KE)或国家名称(例如 Kenya)。未知值返回400。
methodology方法学目录代码,不区分大小写并忽略空格(例如 VM0048)。未知值返回400,并列出相近的代码。
sector项目类型:arr、biochar、biogas、biomass、blue_carbon、cookstoves、dac、industrial、industrial_gases、methane、other、redd、renewable_energy、soil_carbon、water。未知值返回400。
limit1至200之间的十进制整数,默认50。
offset非负十进制整数,默认0。

额度与合理使用

  • 300 次请求/天/密钥,为默认上限,由 REST 与 MCP 共享。
  • 30 个不同高级版项目/天,由网站、PDF 报告、REST 与 MCP 共享。同一天重复打开同一项目只计一次。投资组合中的项目及为您解锁的项目不占此额度;仅返回公开记录也不消耗项目额度。
  • Pro:每个密钥每天 1,000 次请求,每天 300 个不同的项目;其他与上述相同。
  • 20 次报价核查/天/账户,与网站报价核查共享。

每日计数在 UTC 00:00 重置。另外,每个 IP 每分钟最多120次请求。列表和统计请求计入请求次数,但不消耗高级版项目额度。

错误

状态码含义与处理方法
400项目标识符或列表参数无效。请检查错误消息和允许值。
401密钥缺失、无效、已撤销,或没有有效的高级版访问权限。请检查 Authorization 请求头及账户。
403登录访问令牌所属账户没有有效的高级版访问权限。请检查您的账户。
404未找到项目。请核对登记编号或 slug。
429已达请求、突发请求或项目额度。请按 Retry-After 响应头等待。
503项目正在更新。请按 Retry-After 等待后重试。

请求示例

先获取筛选列表,再按登记编号请求单个记录。第二次请求可能消耗一次高级版项目额度。

curl 'https://carbonmeld.com/api/v1/projects?registry=VCS&min_score=7&limit=5&offset=0' \
  -H 'Authorization: Bearer cmk_YOUR_KEY_HERE'

curl 'https://carbonmeld.com/api/v1/projects/VCS-1318' \
  -H 'Authorization: Bearer cmk_YOUR_KEY_HERE'
查看示例项目:VCS-1318

API 的功能边界

此接口提供 CarbonMeld 数据的只读访问,不接入登记处的签发或 MRV 工作流,不签发或转移信用,也不验证单个序列号的所有权。登记处标签和记录数量反映我们持有的数据,并不构成对报价的保证。

条款

将数据用于工作前,请阅读使用条件与评级方法说明。

使用条款

在 AI 助手中使用

MCP 服务器使用相同的 API 密钥和额度。

MCP 指南

GitHub 上的配置示例和 MCP Registry 条目