Data Models

This page documents all data models used in the QAirbon STAC API. All responses conform to the STAC specification v1.0.0 and GeoJSON format.

Model Index

StacCatalog

Root catalog object with API metadata and links
StacCollection

Collection metadata with extent and summaries
StacItem

Individual site as a GeoJSON Feature
SiteProperties

Site metadata including emissions and production
StacFeatureCollection

Paginated collection of STAC items
StacSearchRequest

Search request body with spatial filters
SAIProperties

Site Activity Index observation properties
PlumeProperties

CO₂ plume inversion event properties
QAIProperties

Qairbon Activity Index observation properties
AlertProperties

Blast furnace restart / shutdown alert properties
NewsProperties

Press article mentioning a site

StacCatalog

The root catalog object returned by the STAC landing page endpoint. Contains API metadata, conformance information, and navigation links.

Property Type Description
type string Always "Catalog"
stac_version string STAC specification version ("1.0.0")
id string Unique identifier for the catalog
title string Human-readable title
description string Description of the catalog contents
conformsTo string[] Array of conformance class URIs
links StacLink[] Navigation links (self, root, collections, search)

Example

{
  "type": "Catalog",
  "stac_version": "1.0.0",
  "id": "qairbon-stac",
  "title": "QAirbon STAC API",
  "description": "Industrial sites monitoring data catalog",
  "conformsTo": [
    "https://api.stacspec.org/v1.0.0/core",
    "https://api.stacspec.org/v1.0.0/collections",
    "https://api.stacspec.org/v1.0.0/item-search"
  ],
  "links": [
    {"rel": "self", "href": "/api/v1/stac"},
    {"rel": "root", "href": "/api/v1/stac"},
    {"rel": "data", "href": "/api/v1/collections"},
    {"rel": "search", "href": "/api/v1/search", "method": "POST"}
  ]
}

StacCollection

Describes a collection of related STAC items. The API currently has one collection: sites.

Property Type Description
type string Always "Collection"
stac_version string STAC specification version
id string Collection identifier (e.g., "sites")
title string Human-readable title
description string Detailed description of the collection
license string License identifier (e.g., "proprietary")
extent StacExtent Spatial and temporal extent of items
links StacLink[] Navigation links

Example

{
  "type": "Collection",
  "stac_version": "1.0.0",
  "id": "sites",
  "title": "Industrial Sites",
  "description": "Global industrial facilities including steel and copper plants",
  "license": "proprietary",
  "extent": {
    "spatial": {
      "bbox": [[-180, -90, 180, 90]]
    },
    "temporal": {
      "interval": [[null, null]]
    }
  },
  "links": [...]
}

StacItem

Represents a single industrial site as a GeoJSON Feature with STAC-compliant metadata. This is the primary data object returned by the API.

Property Type Description
type string Always "Feature" (GeoJSON type)
stac_version string STAC specification version
stac_extensions string[] List of STAC extension URIs used
id string (UUID) Unique site identifier
collection string Parent collection ID ("sites")
geometry GeoJSONGeometry Site location as a GeoJSON Point
bbox number[] Bounding box [west, south, east, north]
properties SiteProperties Site metadata and attributes
links StacLink[] Navigation links
assets object Associated assets (optional)

Example

{
  "type": "Feature",
  "stac_version": "1.0.0",
  "id": "9d8b3de5-322f-45a3-9666-df4c25d6ae34",
  "collection": "sites",
  "geometry": {
    "type": "Point",
    "coordinates": [127.74865, 34.920086]
  },
  "bbox": [127.74865, 34.920086, 127.74865, 34.920086],
  "properties": {
    "datetime": "2020-01-01T00:00:00Z",
    "title": "POSCO Gwangyang steel plant",
    "qairbon:industry": "steel_bf",
    "site:status": "operating",
    "qairbon:country": "South Korea"
  },
  "links": [...]
}

SiteProperties

Contains all metadata for an industrial site, including identification, location, emissions data, production metrics, and corporate ownership information.

Core Properties

Property Type Description
datetime string Nominal datetime (start of monitoring), ISO 8601
title string Full name of the industrial site
qairbon:industry string Industry: steel_bf or copper_smelter_primary — see Industries
site:status string | null Operational status: operating, operating pre-retirement, construction, mothballed, cancelled, announced, retired
site:is_validated boolean | null Whether the site has been validated by an operator (admin/validator only)

Location Properties

Property Type Description
qairbon:country string Country name (e.g., "South Korea")
qairbon:continent string | null Continent name

Activity (SAI-derived)

Property Type Description
sai:activity_1m number | null Most recent Site Activity Index value (current month)
sai:activity_3m number | null Average SAI over the last 3 months
sai:activity_1y number | null Average SAI over the last 12 months
sai:activity_5y number | null Average SAI over the last 60 months
sai:activity_delta_1m number | null activity_1m minus the previous SAI point
sai:activity_delta_3m number | null activity_1m minus activity_3m
sai:activity_delta_1y number | null activity_1m minus activity_1y
sai:activity_delta_5y number | null activity_1m minus activity_5y

Production & Emissions

Property Type Description
site:blast_furnace_count integer | null Number of blast furnace assets at this site
site:plume_count integer | null Total number of CO₂ plume inversions for this site
site:corporates CorporateOwnership[] List of corporate owners with ownership percentages
site:inventories InventoryRecord[] Reported production / emissions inventory records
site:estimates EstimateRecord[] Modelled production / emissions estimate records

CorporateOwnership

Represents ownership stake in an industrial site by a corporate entity.

Property Type Description
company_name string Name of the owning company
ownership_percentage number Percentage of ownership (0-100)
effective_date string Date ownership became effective

Example

{
  "company_name": "POSCO Holdings Inc.",
  "ownership_percentage": 100.0,
  "effective_date": "2022-03-02"
}

InventoryRecord

Historical emissions data from verified inventory sources.

Property Type Description
year integer Reporting year
source string Data source (e.g., "EPA", "EU ETS")
co2_emissions number CO2 emissions in metric tons
scope string Emissions scope (1, 2, or 3)

EstimateRecord

Emissions estimates derived from satellite data or modeling.

Property Type Description
year integer Estimate year
method string Estimation methodology
co2_emissions number Estimated CO2 emissions in metric tons
uncertainty number Uncertainty percentage

StacFeatureCollection

A paginated collection of STAC items returned by list and search endpoints. Follows the GeoJSON FeatureCollection format.

Property Type Description
type string Always "FeatureCollection"
features StacItem[] Array of STAC items
links StacLink[] Pagination and navigation links
numberMatched integer Total number of items matching the query
numberReturned integer Number of items in this response
context object Additional context (returned, limit, matched)

Example

{
  "type": "FeatureCollection",
  "features": [
    { /* StacItem objects */ }
  ],
  "links": [
    {"rel": "self", "href": "/api/v1/collections/sites/items?page=1&limit=10"},
    {"rel": "next", "href": "/api/v1/collections/sites/items?page=2&limit=10"}
  ],
  "numberMatched": 156,
  "numberReturned": 10,
  "context": {
    "returned": 10,
    "limit": 10,
    "matched": 156
  }
}

StacSearchRequest

Request body for the POST search endpoint. Supports spatial filtering using bounding boxes or GeoJSON geometries.

Property Type Required Description
collections string[] No Filter by collection IDs (default: all)
ids string[] No Filter by specific item IDs
bbox number[] No Bounding box: [west, south, east, north]
intersects GeoJSONGeometry No GeoJSON geometry to intersect with
datetime string No Datetime filter (single or range)
limit integer No Maximum results to return (default: 10, max: 100)
page integer No Page number for pagination (default: 1)

Example - Bounding Box Search

{
  "collections": ["sites"],
  "bbox": [126.0, 33.0, 130.0, 38.0],
  "limit": 20
}

Example - Polygon Intersection

{
  "intersects": {
    "type": "Polygon",
    "coordinates": [[[126.0, 33.0], [130.0, 33.0], [130.0, 38.0], [126.0, 38.0], [126.0, 33.0]]]
  },
  "limit": 50
}

GeoJSONGeometry

A GeoJSON geometry object. Used for site locations (Point) and footprints (Polygon), as well as spatial search filters.

Property Type Description
type string Geometry type: Point, Polygon, MultiPolygon, etc.
coordinates array Coordinate array (format varies by geometry type)

Point Example

{
  "type": "Point",
  "coordinates": [127.74865, 34.920086]  // [longitude, latitude]
}

Polygon Example

{
  "type": "Polygon",
  "coordinates": [
    [  // Exterior ring (counter-clockwise)
      [127.7, 34.9],
      [127.8, 34.9],
      [127.8, 35.0],
      [127.7, 35.0],
      [127.7, 34.9]  // First point repeated to close
    ]
  ]
}

Navigation link following the STAC Link specification. Used for pagination, parent/child relationships, and related resources.

Property Type Required Description
href string Required URL of the linked resource
rel string Required Link relation type (see below)
type string No Media type (e.g., application/json)
title string No Human-readable title
method string No HTTP method (for non-GET links)

Common Link Relations

Relation Description
self Link to the current resource
root Link to the STAC catalog root
parent Link to the parent resource
collection Link to the parent collection
items Link to collection items
next Link to next page of results
prev Link to previous page of results

SAIProperties

Properties object for a SAI (Site Activity Index) STAC item. Available under GET .../sai/items. SAI items have a point geometry matching the parent site.

Property Type Description
datetime string (ISO 8601) Observation date (imagery acquisition date, UTC)
sai:value number [0–1] Site Activity Index value (0 = inactive, 1 = fully active)
sai:uncertainty_min number | null Lower bound of the uncertainty interval
sai:uncertainty_max number | null Upper bound of the uncertainty interval
sai:version string SAI algorithm version (e.g., "2.1")
qairbon:site_id string (UUID) UUID of the parent site
title string Parent site full name (multi-site SAI items only)
qairbon:industry string Industry type of the parent site (multi-site SAI items only)

Example

{
  "type": "Feature",
  "stac_version": "1.0.0",
  "id": "a1b2c3d4-1234-5678-abcd-ef0123456789",
  "collection": "sai-9d8b3de5-...",
  "geometry": { "type": "Point", "coordinates": [127.748, 34.920] },
  "properties": {
    "datetime": "2024-06-15T00:00:00Z",
    "sai:value": 0.82,
    "sai:uncertainty_min": 0.78,
    "sai:uncertainty_max": 0.86,
    "sai:version": "2.1",
    "qairbon:site_id": "9d8b3de5-..."
  },
  "links": [...]
}

PlumeProperties

Properties object for a CO₂ plume STAC item. Available under GET .../plume/items. The geometry is a MultiPolygon representing the detected CO₂ plume delineation. Each item has a raster asset link returning a 4-band RGBA GeoTIFF.

Property Type Description
datetime string (ISO 8601) Acquisition date of the imagery used for the inversion
plume:quantification number CO₂ emission rate in tonnes per hour (t/h)
plume:uncertainty number Uncertainty on the emission rate (t/h, 1-sigma)
plume:version string Plume inversion algorithm version
qairbon:asset_id string (UUID) Identifier of the source asset (e.g., blast furnace)
plume:asset_name string Asset type name (e.g., "blast_furnace")

Raster Asset

Each plume STAC item includes a raster asset: a 4-band RGBA GeoTIFF in EPSG:4326, with a white → deep-red color ramp applied to the CO₂ concentration. Transparent pixels represent no-data (outside the detection area).

Example

{
  "type": "Feature",
  "id": "e5f6a7b8-...",
  "collection": "plume-9d8b3de5-...",
  "geometry": { "type": "MultiPolygon", "coordinates": [...] },
  "bbox": [127.70, 34.88, 127.80, 34.96],
  "properties": {
    "datetime": "2024-06-20T10:32:00Z",
    "plume:quantification": 45.3,
    "plume:uncertainty": 8.1,
    "plume:version": "1.0",
    "qairbon:asset_id": "c1d2e3f4-...",
    "plume:asset_name": "blast_furnace"
  },
  "assets": {
    "raster": {
      "href": "/api/v1/collections/sites/items/{site_id}/plume/items/{plume_id}/assets/raster",
      "type": "image/tiff; application=geotiff",
      "title": "CO2 Concentration Raster",
      "roles": ["overview"]
    }
  }
}

QAIProperties

Properties object for a QAI (Qairbon Activity Index) STAC item. Available under GET .../qai/items. QAI is a monthly aggregation of SAI values across all sites in a panel, weighted by production capacity.

Property Type Description
datetime string (ISO 8601) Start of the month represented by this observation
qai:value number [0–1] Qairbon Activity Index value for the panel this month
qai:uncertainty_min number | null Lower bound of the uncertainty interval
qai:uncertainty_max number | null Upper bound of the uncertainty interval
qai:version string SAI algorithm version used to compute this QAI value
qairbon:panel_id string (UUID) UUID of the parent panel
qai:site_count integer Number of sites contributing to this QAI value

Example

{
  "type": "Feature",
  "id": "2024-06",
  "collection": "qai-f1a2b3c4-...",
  "geometry": { "type": "Polygon", "coordinates": [...] },
  "properties": {
    "datetime": "2024-06-01T00:00:00Z",
    "qai:value": 0.74,
    "qai:version": "1.0",
    "qairbon:panel_id": "f1a2b3c4-...",
    "qai:site_count": 18
  }
}

AlertProperties

Properties object for an alert STAC item. Available under GET /collections/alerts/items and GET .../sites/items/{site_id}/alerts/items. Geometry is the blast furnace centroid. Fields are namespaced under the alert and qairbon STAC extensions.

Property Type Description
datetime string (ISO 8601) Event date
title string | null Full name of the parent site
alert:processing_date string (ISO 8601) Date the alert was computed
alert:level string suspected or confirmed
alert:event string restart or shutdown
alert:detection_probability number [0–1] | null Detection confidence
alert:qualitative_cl string | null undefined, low, medium or high
qairbon:asset_id string (UUID) Blast furnace asset
qairbon:site_id string (UUID) | null Parent site
qairbon:country string | null Country of the parent site

Example

{
  "type": "Feature",
  "id": "0190a1b2-...",
  "collection": "alerts",
  "geometry": { "type": "Point", "coordinates": [139.95, 35.35] },
  "properties": {
    "datetime": "2026-07-28T00:00:00Z",
    "title": "Kimitsu Works",
    "alert:processing_date": "2026-07-30T03:00:00Z",
    "alert:level": "confirmed",
    "alert:event": "shutdown",
    "alert:detection_probability": 0.91,
    "alert:qualitative_cl": "high",
    "qairbon:asset_id": "7c3e...",
    "qairbon:site_id": "6af8...",
    "qairbon:country": "Japan"
  }
}

NewsProperties

Properties object for a news STAC item. Available under GET /collections/news/items and GET .../sites/items/{site_id}/news/items. Geometry is the site footprint. Fields are namespaced under the news and qairbon STAC extensions.

Property Type Description
datetime string (ISO 8601) Publication date (falls back to the processing date when the article carries none)
title string | null Article headline
description string | null Verbatim quote from the article mentioning the site
news:url string (URL) Canonical URL of the article (also exposed as a via link)
news:source string | null Publisher name
news:category string | null Subject category, see the category query parameter for the values
news:mechanism string | null rss, news_sitemap or listing_scrape
news:processing_date string (ISO 8601) | null Date the article was ingested
news:site_name string | null Full name of the mentioned site
qairbon:site_id string (UUID) Mentioned site
qairbon:country string | null Country of the mentioned site

Example

{
  "type": "Feature",
  "id": "0190a1b2-...",
  "collection": "news",
  "geometry": { "type": "Polygon", "coordinates": [...] },
  "properties": {
    "datetime": "2026-09-07T10:00:00Z",
    "title": "Nippon Steel idles Kimitsu blast furnace",
    "description": "Kimitsu No. 2 blast furnace was idled for relining",
    "news:processing_date": "2026-09-08T03:00:00Z",
    "news:source": "Kallanish",
    "news:category": "production_capacity",
    "news:url": "https://www.kallanish.com/...",
    "news:mechanism": "rss",
    "news:site_name": "Kimitsu Works",
    "qairbon:site_id": "6af8...",
    "qairbon:country": "Japan"
  }
}

StacExtent

Defines the spatial and temporal bounds of a collection.

Property Type Description
spatial object Contains bbox: array of bounding boxes
temporal object Contains interval: array of datetime ranges

Example

{
  "spatial": {
    "bbox": [[-180, -90, 180, 90]]
  },
  "temporal": {
    "interval": [["2020-01-01T00:00:00Z", null]]
  }
}