API 文档 | 经济综合观察站

OEC Pro API 文档

PRO

介绍

欢迎使用 OEC PRO API。在本文件中, 您将学习如何构建各种 API 端点, 以获取所需的特定数据切片。您还将学习如何使用数据探索器, 这是一个用户界面, 用于方便地构建 API 查询并轻松在浏览器中查看数据。

要开始, 您首先需要注册为专业用户, 如果您还没有这样做的话。成功注册并使用新专业账户登录后, 您应该会看到以下页面, 其中包含用于验证您所有 API 请求的令牌。

请注意:

您应该将您的 API 令牌视为密码, 并确保不与任何人分享或在线发布, 以免他人使用它代表您发出请求。如果您在任何时候需要生成新的令牌, 只需转到您的用户账户页面, 单击令牌旁边的按钮即可生成新的令牌。

进行您的第一次数据请求

获取数据很简单! OEC API 旨在实现互操作性, 可以与许多不同的程序集成。以下是一个示例, 展示如何请求美国海关港口级数据的最新月份出口。

curl --request GET --url "https://api-v2.oec.world/tesseract/data.jsonrecords?time=time.latest&include=Trade+Flow:2&cube=trade_s_usa_port_m_hs&drilldowns=Time,Product,Trade+Flow&measures=Trade+Value&token=YOUR_API_TOKEN"

import requests
import pandas as pd

r = requests.get("https://api-v2.oec.world/tesseract/data.jsonrecords?time=time.latest&include=Trade+Flow:2&cube=trade_s_usa_port_m_hs&drilldowns=Time,Product,Trade+Flow&measures=Trade+Value&token=YOUR_API_TOKEN")
df = pd.DataFrame(r.json()["data"])
print(df.head())

<?php
  $url = 'https://api-v2.oec.world/tesseract/data.jsonrecords?time=time.latest&include=Trade+Flow:2&cube=trade_s_usa_port_m_hs&drilldowns=Time,Product,Trade+Flow&measures=Trade+Value&token=YOUR_API_KEY' ;
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_TIMEOUT, 200);
  curl_setopt($ch, CURLOPT_SSLVERSION, 6);
  curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 20);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  curl_close($ch);
  $json = json_decode($response, true);
?>

URL url = new URL("https://api-v2.oec.world/tesseract/data.jsonrecords?time=time.latest&include=Trade+Flow:2&cube=trade_s_usa_port_m_hs&drilldowns=Time,Product,Trade+Flow&measures=Trade+Value&token=YOUR_API_KEY");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
try (var reader = new BufferedReader(
  new InputStreamReader(conn.getInputStream()))) {
    for (String line; (line = reader.readLine()) != null; ) {
      result.append(line);
    }
  }

{
  "data": [
    {
      "Time": 202102,
      "Product ID": 1010121,
      "Product": "Horses: live, pure-bred breeding animals",
      "Trade Flow ID": 2,
      "Trade Flow": "Exports",
      "Trade Value": 7440995
    },
    {
      "Time": 202102,
      "Product ID": 1010129,
      "Product": "Horses: live, other than pure-bred breeding animals",
      "Trade Flow ID": 2,
      "Trade Flow": "Exports",
      "Trade Value": 4387319
    },
    ...
  ],
  "source": [
    {
      "name": "trade_s_usa_port_m_hs",
      "measures": [
        "Trade Value"
      ],
      "annotations": {
        "source_description": "Monthly trade data for the United States",
        "dataset_name": "USA Trade® Online",
        "dataset_link": "https://usatrade.census.gov/index.php",
        "topic": "National",
        "source_name": "United States Census Bureau",
        "table": "Port",
        "subtopic": "United States"
      }
    }
  ]
}

使用数据探索器生成 API URL

让我们开始几个示例, 帮助我们学习如何使用数据探索器。您可以直接从您的账户页面访问数据探索器, 或通过访问 https://oec.world/zh/explorer.

示例 1

中国最新的月度产品贸易数据

登录后, 您应该会看到以下屏幕。左侧是您开始构建查询的地方。那么让我们直接进入第一个示例!

•首先, 我们需要选择适当的数据集, 在我们的案例中, 这将是中国区域立方体。在“数据集”标题下, 从下拉列表中选择“国家”和“中国”。

•

其次, 让我们选择贸易价值和数量从度量列表中。

•接下来, 我们应该从下钻菜单中按顺序选择以下维度:

•
产品: 在我们所寻找的层级水平上。在本示例中, 我们将选择HS4 (指的是 4 位数字的协调系统产品分类) 。
•
时间: 在月份层级水平上。

•

最后, 让我们添加一个切割:

•
时间: 时间戳格式为 YYYYMM, 因此如果我们搜索 202012, 我们将获得 2020 年 12 月的数据。

数据表

单击“执行查询”按钮后, 您应该会看到以下结果。结果将包含我们在之前的数据选择步骤中选择的任何列作为下钻或度量。

现在我们的数据已被检索, 我们可以对结果进行排序和格式化。单击任何度量列旁边的箭头按钮将弹出一个菜单, 允许我们对该列的结果进行排序或格式化。

API Endpoint

最后, 一旦我们对数据选择感到满意, 我们可以单击“API 视图”选项卡, 找到用于创建我们在“数据表”视图中看到的数据的特定 API 端点 URL。

技术定义

现在我们已经看到了如何根据特定数据选择生成数据表的第一个示例, 让我们更仔细地看看一些技术术语。

•
数据集:
数据集是 OEC API 使用的基本数据结构。数据集包含与特定主题和特定来源相关的所有数据。例如: 您将看到多个国际贸易数据集, 因为我们有多种不同的产品分类: SITC (标准国际贸易分类) 、HS (协调系统) 以及不同的修订版本, 如 HS92 (协调系统的 1992 年修订) 、HS96 (协调系统的 1996 年修订) 等。
每个立方体中的数据可以按维度进行分解。我们可以将维度想象为立方体的一个边, 边的长度取决于维度。正如您所看到的, 维度只是我们可以按其分组的变量。
总之, 立方体以最细分的级别存储大量数据。以这种方式存储数据允许最终的灵活性, 因为列始终可以被边际化并聚合其值。
•
下钻:
下钻是数据集维度。使用立方体隐喻思考数据集, 维度将是边缘。默认情况下, 数据集将按所有维度聚合, 从下钻菜单中选择一个允许我们按该维度进行分解。
以德国区域数据集为例, 它具有时间、区域和产品类型作为维度。每个维度将在 OEC API 中作为下钻出现。因此, 创建请求的第一步是指定至少一个下钻, 以便检索该特定变量的数据。
通常需要按不同的层级水平对数据进行分组。例如, 我们开始分析时检索年度贸易数据, 并希望转向更高的粒度水平, 例如季度或月份。这就是为什么维度还支持不同的层级水平。层级水平是按分类的固有层级尊重数据分组的好方法。我们在定义中具有子维度的维度中提到层级水平。例如, 区域可以按国家分组, 国家可以按洲分组。
当我们使用数据探索器创建查询时, 我们必须决定希望按哪个层级对数据进行分组以及要包含哪些层级。
•
度量:
每个立方体包含不同的度量。这就是为什么根据所选的立方体和维度, 查询将有不同的度量可用。度量是可以聚合的数据值。度量可以支持不同类型的聚合, 例如总和、平均值、最小值或最大值。因此, 度量通常是整数、浮点数或百分比变量。在我们的案例中, 度量的示例包括贸易价值、重量、数量等。
•
切割:
切割允许我们根据所选维度的特定成员过滤数据。例如, 如果我们使用美国次国家立方体并希望查看来自科罗拉多州的出口数据 (而不是显示所有州) , 我们将对该特定成员进行切割。
•
高级选项:
1. •
  调试 MDX: 此选项启用调试工具, 当查询无法正常工作时, 将指示错误所在。
2. •
  应用唯一: 此选项作为过滤器, 过滤重复的 ID, 仅保留唯一值。
3. •
  仅返回非空数据: 此选项将跳过缺少值的结果。
4. •
  包括父级: 此选项将在查询中包括父维度, 以便为具有父维度的下钻添加。
5. •
  优化稀疏结果: 此选项将跳过度量为 null 值的行。