API Specification

Overview

The WBA Data API provides programmatic access to query and download WBA data directly through REST endpoints. This enables integration of WBA benchmark data into your own applications, research tools, and data pipelines.

All data available in the Data Explorer portal can also be accessed via the API, with the same datasets and columns. This approach may evolve in the future as we receive feedback and improve the platform.

Base URL: https://wba-repository.opendataservices.coop/api/data/v1

API Specification: OpenAPI 3.1 (OAS 3.1)

Requesting Access

API access requires approval. To request access:

  1. Sign in to the Data Explorer
  2. Click Request Access on the homepage
  3. Your request is submitted automatically for your user account
  4. You will be redirected to a status screen showing your request is being processed
  5. After a few moments, the screen will confirm that your request has been submitted and is under review by WBA
  6. A contact email is provided if you need to reach WBA regarding your request

Important: As we have recently launched the platform, the approval process may take several days. Please be patient while we review requests.

wbaportal_api_requestprocess wbaportal_api_requestpending wbaportal_api_accessgranted

Checking Your API Access Status

To check if your API access has been approved:

  1. Sign in to the Data Explorer
  2. Click Request Access on the homepage
  3. You will see one of the following:
    • Request pending: Your request is still under review
    • Access granted: Your API key will be displayed on the screen

Note: You will not receive an email notification when your access is approved. Please check your status periodically through the portal.

Authentication

Once approved, all API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Setup (save Base URL as variable):

BASE_URL="https://wba-repository.opendataservices.coop/api/data/v1"

Example request:

curl -X GET "$BASE_URL/datasets" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Available Endpoints

The API provides two main endpoint groups: Datasets for querying data and Downloads for bulk data export.

Datasets Endpoints

GET /datasets — List all available datasets

GET /datasets/{dataset_name} — Get rows from a specific dataset

GET /datasets/{dataset_name}/cols — Get column metadata for a dataset

GET /datasets/{dataset_name}/cols/{col_name} — Get unique values for a specific column

Downloads Endpoints

GET /downloads/datasets/{dataset_name} — Initiate a dataset download (queued task)

GET /downloads/download/{download_id} — Check download task status

GET /downloads/{file_name} — Download the generated file

GET /downloads/full/{static_file} — Download pre-generated static file (full dataset)

Available Datasets

The following datasets are available via the API:

Company Data

  • Companies (companies)
  • Footprint Attributes (footprintattributes)
  • Climate Profiles (climateprofiles)
  • Emissions (emissions)
  • Targets (targets)
  • Sources (sources)

Methodology Data

  • Methodology Measurement Areas (methodologymeasurementareas)
  • Methodology Indicators (methodologyindicators)
  • Methodology Elements (methodologyelements)
  • Methodology Attributes (methodologyattributes)

Benchmark Data

  • Benchmarks (benchmarks)
  • Measurement Areas (measurementareas)
  • Indicators (indicators)
  • Elements (elements)
  • Attributes (attributes)

Query Parameters

Pagination Parameters

These parameters are available on all dataset row listing endpoints.

order_by (string) — Column name to sort by. Default: None

ascending (boolean) — Sort order (true = ascending, false = descending). Default: false

per_page (integer) — Number of rows per page. Default: 10

page (integer) — Page number (1-indexed). Default: 1

Filtering Parameters

Filter parameters use the column name with an optional operator suffix. Multiple filters can be combined.

{column_name} or {column_name}_eq — Equals. Example: company_name=Nestlé

{column_name}_gt — Greater than. Example: benchmark_score_numerical_gt=50

{column_name}_lt — Less than. Example: benchmark_score_numerical_lt=50

{column_name}_ge — Greater than or equal. Example: methodology_year_ge=2024

{column_name}_le — Less than or equal. Example: methodology_year_le=2023

{column_name}_ne — Not equals. Example: company_ownership_ne=Private

{column_name}_co — Contains substring (string columns only). Example: company_name_co=Bank

{column_name}_sw — Starts with (string columns only). Example: company_id_sw=PT_00

{column_name}_ew — Ends with (string columns only). Example: company_website_ew=.com

All string comparisons are case-insensitive. Boolean values can be True, true, 1 or False, false, 0.

Column Selection Parameters

include (comma-separated strings) — Columns to include in response

exclude (comma-separated strings) — Columns to exclude from response

These parameters should not be used together.

Response Formats

Dataset List Response

[
  {
    "name": "Companies",
    "slug": "companies",
    "description": "",
    "cols": 29,
    "rows": 2000,
    "updated": "2026-01-10T09:41:20"
  }
]

Dataset Rows Response

{
  "data": [
    {
      "id": "abc123...",
      "company_id": "PT_00001",
      "company_name": "Example Corp"
    }
  ],
  "meta": {
    "rows": 2000
  }
}

Column Metadata Response

[
  {
    "name": "company_id",
    "title": "Company ID",
    "type": "str",
    "display": true
  }
]

Column Values Response

{
  "options": [
    "Value 1",
    "Value 2"
  ]
}

Download Workflow

Downloading data via the API is an asynchronous process. Download tasks are placed in a queue and executed sequentially.

Dynamic Downloads (Filtered/Custom)

Use this method when you need to apply filters or select specific columns.

Step 1: Initiate Download

Request a download for a dataset. You can optionally apply filters and column selection.

curl -X GET "$BASE_URL/downloads/datasets/companies" \
  -G -d "data_format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "download_id": "82ac309d-3fd2-4bc9-874b-a6dfbdaa677a"
}

Step 2: Check Status

Poll the download status endpoint until the task is complete.

DOWNLOAD_ID="82ac309d-3fd2-4bc9-874b-a6dfbdaa677a"

curl -X GET "$BASE_URL/downloads/download/$DOWNLOAD_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (in progress):

{
  "download_id": "82ac309d-3fd2-4bc9-874b-a6dfbdaa677a",
  "state": "PENDING"
}

Response (complete):

{
  "download_id": "82ac309d-3fd2-4bc9-874b-a6dfbdaa677a",
  "state": "SUCCESS",
  "file": "dataset-companies-20260110.zip"
}

Step 3: Download File

Once the status shows SUCCESS, download the file using the filename returned.

curl -X GET "$BASE_URL/downloads/dataset-companies-20260110.zip" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o companies-data.zip

The file will be saved locally as companies-data.zip.

Static Downloads (Full Datasets)

For downloading complete datasets without filters, you can use the static download endpoint. These files are pre-generated and available immediately (no queue).

File naming convention:

  • dataset-{dataset_name}-full.zip

Example:

curl -X GET "$BASE_URL/downloads/full/dataset-companies-full.zip" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o companies-full.zip

Example Requests

All examples below assume you have set the BASE_URL variable:

BASE_URL="https://wba-repository.opendataservices.coop/api/data/v1"

List all datasets

curl -X GET "$BASE_URL/datasets" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get companies in the Food Production industry

curl -X GET "$BASE_URL/datasets/companies" \
  -G -d "company_wba_industry=Food Production" \
  -d "per_page=50" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get benchmark scores above 60

curl -X GET "$BASE_URL/datasets/benchmarks" \
  -G -d "benchmark_score_numerical_gt=60" \
  -d "order_by=benchmark_score_numerical" \
  -d "ascending=false" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get only specific columns

curl -X GET "$BASE_URL/datasets/companies" \
  -G -d "include=company_id,company_name,company_wba_industry" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get unique values for a column

curl -X GET "$BASE_URL/datasets/sources/cols/source_type" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

The API returns standard HTTP status codes:

200 — Success

401 — Unauthorized (invalid or missing API key)

404 — Not Found (dataset or resource not found)

422 — Validation Error (invalid parameters)

500 — Internal Server Error

Error responses include a detail message:

{
  "detail": "Dataset 'invalid_name' not found"
}

Rate Limits

To ensure fair usage and platform stability, the API is limited to 1 request per second per API key.

If you exceed this limit, you may receive a 429 Too Many Requests response. If this happens, wait a moment before retrying your request.

For bulk data needs, we recommend using the download endpoints rather than making many individual requests.

Token Expiration and Renewal

API access tokens expire after 24 hours. For automated pipelines, you can retrieve your current valid token programmatically using the authentication endpoint:

curl -X GET "$BASE_URL/auth/request/" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"

Response:

{
  "email": "[email protected]",
  "requested": true,
  "approved": true,
  "api_key": "YOUR_CURRENT_VALID_TOKEN"
}

This allows you to integrate token retrieval into your data pipelines without manually checking the portal each day.

Contact and Support

If you have any questions, encounter any issues, or need assistance with the Data Explorer or API, please contact us at:

[email protected]

We welcome your feedback and suggestions to help us improve the platform.

Subscribe to stay informed on our work

Keep up to date with all the latest from World Benchmarking Alliance

Join our newsletter
World Benchmarking Alliance
Careers Privacy Policy Disclaimer Documentation Fair Use Donation Contact Us Built by 89up