{
  "openapi": "3.1.0",
  "info": {
    "title": "Trading Agent Data: Emissions Data API",
    "version": "1.0.0",
    "summary": "One company's official reported emissions, by company number, as each source publishes them.",
    "description": "Emissions Data is supplied only under a signed Order Form that names it, and only the layers and sources it names (Data Terms clause 5.1A; Source Conditions Schedule clause 6.2). A key with no such entitlement receives 403 emissions_not_licensed on every endpoint. Free keys and the demo key never read it.\n\nRows are returned as stored. We do not check figures for truth or assure them. We do not add values, turn a site's value into a company's, fill in a Scope or convert a unit. A blank stays blank, and a blank is not a zero.\n\nScope 3 appears only in three sources: France by BEGES category (not the 15 GHG Protocol categories), Taiwan and Spain as totals. There is no Scope 3 for any other country, and none worldwide.\n\nDo not add values across sources, reporter types, gases or sites and describe the result as a company's emissions.",
    "contact": { "email": "william@tradingagentapp.com" },
    "termsOfService": "https://www.tradingagentapp.com/licences/sources"
  },
  "servers": [{ "url": "https://www.tradingagentapp.com" }],
  "security": [{ "bearer": [] }, { "apiKey": [] }],
  "paths": {
    "/api/v1/emissions/{id}": {
      "get": {
        "operationId": "getEmissionsById",
        "summary": "Every row we hold for one company number or facility ID",
        "description": "For an ID with a slash in it, as many European facility IDs have, use GET /api/v1/emissions?id=… instead, or percent-encode the slash.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "306138900" },
          { "$ref": "#/components/parameters/id_type" },
          { "$ref": "#/components/parameters/source" },
          { "$ref": "#/components/parameters/layer" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/scope" },
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": {
          "200": { "description": "The rows for this page. An ID we hold nothing for answers count 0, which says nothing about that company's emissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmissionsReply" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/NotLicensed" },
          "429": { "description": "Over the key's rate limit" },
          "503": { "description": "A read failed. This does not mean we hold nothing for the ID." }
        }
      }
    },
    "/api/v1/emissions": {
      "get": {
        "operationId": "getEmissionsIndexOrLookup",
        "summary": "What this key may read; with id=, the same lookup as /api/v1/emissions/{id}",
        "parameters": [
          { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "SE.CAED/10017896.Facility" },
          { "$ref": "#/components/parameters/id_type" },
          { "$ref": "#/components/parameters/source" },
          { "$ref": "#/components/parameters/layer" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/scope" },
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": {
          "200": { "description": "Without id: this key's sources with their row counts, years and section of the Source Conditions Schedule. With id: as /api/v1/emissions/{id}." },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/NotLicensed" }
        }
      }
    },
    "/api/v1/emissions/match": {
      "post": {
        "operationId": "matchEmissionsIds",
        "summary": "Which of up to 1,000 IDs we hold, and how many rows",
        "description": "Counts rows this key may read. It returns no figures. Not held says nothing about a company's emissions.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["ids"],
                "properties": {
                  "id_type": { "$ref": "#/components/schemas/IdType" },
                  "source": { "type": "string", "description": "For id_type facility." },
                  "ids": {
                    "type": "array",
                    "maxItems": 1000,
                    "items": {
                      "oneOf": [
                        { "type": "string" },
                        {
                          "type": "object",
                          "required": ["id"],
                          "properties": { "id": { "type": "string" }, "id_type": { "$ref": "#/components/schemas/IdType" }, "source": { "type": "string" } }
                        }
                      ]
                    }
                  }
                }
              },
              "example": { "id_type": "siren", "ids": ["306138900", "542051180"] }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per ID.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "const": "emissions_match" },
                    "requested": { "type": "integer" },
                    "held": { "type": "integer" },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": ["string", "null"] },
                          "id_type": { "type": ["string", "null"] },
                          "held": { "type": "boolean" },
                          "rows": { "type": "integer", "description": "A count of rows, never an emissions figure." },
                          "error": { "type": "string", "description": "Why this ID could not be looked up, such as invalid_id." },
                          "by_source": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "source": { "type": "string" },
                                "layer": { "$ref": "#/components/schemas/Layer" },
                                "rows": { "type": "integer" },
                                "years": { "type": ["array", "null"], "items": { "type": "integer" } },
                                "scope3_rows": { "type": "integer" }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/NotLicensed" },
          "413": { "description": "Body too large" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": { "type": "http", "scheme": "bearer" },
      "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" }
    },
    "parameters": {
      "id_type": { "name": "id_type", "in": "query", "required": true, "description": "Required with an id: a stock code and a facility ID can be the same digits.", "schema": { "$ref": "#/components/schemas/IdType" }, "example": "siren" },
      "source": { "name": "source", "in": "query", "schema": { "type": "string" }, "description": "Comma list of source names. Required, as one name, with id_type facility: a facility ID means something only inside its source.", "example": "fr" },
      "layer": { "name": "layer", "in": "query", "schema": { "type": "string" }, "description": "Comma list of reported and related, or modelled on its own. Modelled rows are supplied apart: they come only with layer=modelled, and a reply without it says how many there are in modelled_rows_not_in_this_reply." },
      "year": { "name": "year", "in": "query", "schema": { "type": "string" }, "description": "A four-digit year, or a comma list.", "example": "2022" },
      "scope": { "name": "scope", "in": "query", "schema": { "type": "string" }, "description": "Comma list of 1, 2, 3 and blank. Matches the stored scope exactly; a row whose source gives no Scope is blank.", "example": "3" },
      "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 1000 } },
      "offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }
    },
    "responses": {
      "BadRequest": { "description": "A parameter could not be read: invalid_id_type, invalid_id, facility_needs_source, unknown_source, invalid_layer, modelled_not_mixed, invalid_year, invalid_scope, invalid_limit, invalid_offset, invalid_body or too_many_ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "No valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotLicensed": { "description": "emissions_not_licensed: this key has no entitlement. source_not_licensed or layer_not_licensed: the filter names something the Order Form does not.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Layer": { "type": "string", "enum": ["reported", "related", "modelled"], "description": "reported: emissions values reported to a public body. related: other values from the same sources, not greenhouse gas figures. modelled: estimates by the publishing body or a third party, not reports by the company or plant named." },
      "IdType": {
        "type": "string",
        "enum": ["siren", "siret", "tw_stock_code", "nif", "abn", "au_id_as_filed", "ca_bn", "qc_sago", "ico", "rut", "il_corp", "che_uid", "us_ticker", "facility"],
        "description": "siren: France (ADEME; IREP sites, by the first nine digits of their SIRET). siret: France IREP. tw_stock_code: Taiwan. nif (or cif): Spain MITECO and Basque Country PRTR. abn: Australia. au_id_as_filed: an Australian number the source gives that is not 11 digits. ca_bn (or business_number): Canada GHGRP. qc_sago: Québec. ico: Czech Republic. rut: Chile. il_corp (or israeli_company_number): Israel PRTR, the reporting entity's registrar number. che_uid (or uid): Switzerland SwissPRTR, the facility owner's enterprise identification number, CHE-123.456.789. us_ticker: United States, our own link by exact parent name, which can be wrong; the row's join_method says so. facility: a site's ID, with source= (for Massachusetts, source=us_massdep and the MassDEP AQ ID, seven digits with any leading zero)."
      },
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } },
      "Row": {
        "type": "object",
        "description": "A stored row. These fields are always present; other fields the source gives come with them (source_id, id_type, company_name, facility_id, facility_name, level, boundary, as_filed_label and more).",
        "required": ["source", "layer", "year", "scope", "scope_basis", "category", "gas", "metric", "value", "value_raw", "unit", "verified_raw", "filing_date", "flags", "suspect", "source_url", "source_attribution"],
        "properties": {
          "source": { "type": "string" },
          "layer": { "$ref": "#/components/schemas/Layer" },
          "year": { "type": ["integer", "null"] },
          "scope": { "type": ["string", "null"], "description": "As stored: 1, 2, 3 or blank. Never inferred, never filled." },
          "scope_basis": { "type": ["string", "null"], "description": "Where scope came from: the source's own word, or its official method." },
          "category": { "type": ["string", "null"], "description": "The source's own category, such as BEGES P4.1." },
          "gas": { "type": ["string", "null"] },
          "metric": { "type": ["string", "null"] },
          "value": { "type": ["number", "null"], "description": "As filed, in unit. Blank is not zero." },
          "value_raw": { "type": ["string", "null"], "description": "The source's own text for the value." },
          "unit": { "type": ["string", "null"], "description": "As the source gives it. Never converted." },
          "verified_raw": { "type": ["string", "null"], "description": "The source's own field, repeated. Means only what the source means by it." },
          "filing_date": { "type": ["string", "null"], "description": "France: the date ADEME gives for the filing's publication. Blank for every other source." },
          "flags": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Rules the row met. A flag marks what a person should look at; it does not say the figure is wrong." },
          "suspect": { "type": ["string", "null"], "description": "Our opinion that the value should not be relied on without checking. A row with neither flags nor suspect is not shown to be right." },
          "source_url": { "type": ["string", "null"] },
          "source_attribution": { "type": "string", "description": "The full Attribution Notice for this row. Keep it with the row (Schedule clause 6.3)." }
        },
        "additionalProperties": true
      },
      "EmissionsReply": {
        "type": "object",
        "properties": {
          "object": { "const": "emissions" },
          "id": { "type": "string" },
          "id_type": { "$ref": "#/components/schemas/IdType" },
          "data_version": { "type": "string" },
          "data_date": { "type": "string" },
          "count": { "type": "integer", "description": "Rows in this reply." },
          "total": { "type": "integer", "description": "Rows matching the filters. A count of rows, never an emissions figure." },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "has_more": { "type": "boolean" },
          "next_offset": { "type": ["integer", "null"] },
          "entitlement": { "type": "object", "description": "The layers and sources this key may read, and its Order Form reference." },
          "modelled_rows_not_in_this_reply": { "type": "object" },
          "rows_outside_this_entitlement": { "type": "integer" },
          "read_this": { "type": "array", "items": { "type": "string" } },
          "attribution": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "For each source in this reply, the full Attribution Notice or notices." },
          "schema": { "type": "object" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Row" } }
        }
      }
    }
  }
}
