copernicus-iraq-air

Interactive React widget for visualizing CH4 (Methane) and CO (Carbon Monoxide) atmospheric pollution data over Iraq using Copernicus Sentinel-5P satellite imagery.

Built on Mapbox GL with real-time data from the Copernicus Data Space Ecosystem APIs.

Features

• Satellite data overlay on an interactive Mapbox map of Iraq
• CH4 and CO pollutant selection with color-coded concentration heatmaps
• 18 Iraqi governorates with per-province statistical readings (mean, min, max)
• Dynamic date selector loaded from the Copernicus catalogue
• 5-day mosaic compositing for maximum spatial coverage
• Overlay opacity control (0-100%)
• Info tooltips throughout the UI explaining data sources, units, and methodology
• Severity indicators (Low / Moderate / High) per province
• Observation date tracking per province reading
• Dark theme matching professional geospatial dashboards

Installation

npm install copernicus-iraq-air

Prerequisites

1. Mapbox Access Token - Get one at mapbox.com
2. Copernicus Account - Register free at dataspace.copernicus.eu

Quick Start

1. Create a token API route

The widget needs a server-side endpoint to securely obtain Copernicus access tokens. In your Next.js app:

// app/api/copernicus/token/route.ts
import { NextResponse } from 'next/server';
import { getCopernicusToken } from 'copernicus-iraq-air';

let cached: { token: string; expiresAt: number } | null = null;

export async function GET() {
  const now = Date.now();
  if (cached && cached.expiresAt > now + 60_000) {
    return NextResponse.json({ access_token: cached.token });
  }

  const data = await getCopernicusToken(
    process.env.COPERNICUS_USERNAME!,
    process.env.COPERNICUS_PASSWORD!,
  );

  cached = {
    token: data.access_token,
    expiresAt: now + data.expires_in * 1000,
  };

  return NextResponse.json({ access_token: data.access_token });
}

2. Add environment variables

NEXT_PUBLIC_MAPBOX_TOKEN=pk.your_mapbox_token
[email protected]
COPERNICUS_PASSWORD=your_password

3. Use the widget

'use client';

import { useCallback } from 'react';
import { CopernicusWidget } from 'copernicus-iraq-air';
import 'copernicus-iraq-air/styles.css';

export default function AirQualityPage() {
  const getAccessToken = useCallback(async () => {
    const res = await fetch('/api/copernicus/token');
    const data = await res.json();
    return data.access_token;
  }, []);

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <CopernicusWidget
        mapboxToken={process.env.NEXT_PUBLIC_MAPBOX_TOKEN!}
        getAccessToken={getAccessToken}
      />
    </div>
  );
}

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | mapboxToken | string | Yes | - | Mapbox GL access token | | getAccessToken | () => Promise<string> | Yes | - | Async function returning a Copernicus CDSE access token | | className | string | No | - | Additional CSS class for the root container | | defaultPollutant | 'CH4' \| 'CO' | No | 'CH4' | Initial pollutant selection | | defaultProvince | string | No | - | Initial province selection (e.g., 'Baghdad') |

Exports

// Main widget component
import { CopernicusWidget } from 'copernicus-iraq-air';

// Server utility for token management
import { getCopernicusToken } from 'copernicus-iraq-air';

// Constants and configuration
import { IRAQ_PROVINCES, POLLUTANT_CONFIG, THEME } from 'copernicus-iraq-air';

// TypeScript types
import type {
  CopernicusWidgetProps,
  Pollutant,
  ProvinceStats,
  FilterState,
  ProvinceInfo,
} from 'copernicus-iraq-air';

Data Source

All atmospheric data comes from the Copernicus Sentinel-5P satellite carrying the TROPOMI (TROPOspheric Monitoring Instrument):

• Spatial resolution: ~7 km x 3.5 km
• Temporal coverage: Daily global coverage
• CH4 (Methane): Column-averaged dry-air mixing ratio in ppb (parts per billion). Global background ~1900 ppb.
• CO (Carbon Monoxide): Total column in mol/m². Values above 0.05 may indicate significant pollution sources.

Data is accessed via the Copernicus Data Space Ecosystem APIs:

• Sentinel Hub Process API - Generates color-coded raster overlays
• Sentinel Hub Statistical API - Computes per-province aggregated statistics
• Sentinel Hub Catalog API - Discovers available observation dates
• OData Catalog API - Fallback date discovery

How It Works

Map Overlay

The widget fetches a 1024px raster image from the Sentinel Hub Process API covering Iraq's bounding box. A 5-day mosaic (mosaickingOrder: "mostRecent") combines multiple satellite passes to maximize spatial coverage, as a single orbit may not cover all of Iraq.

Province Readings

The Statistical API computes mean/min/max values within each governorate's bounding box using P1D (daily) intervals over the 5-day window. The most recent day with valid observations is selected for each province, which is why the "Obs." date may differ between provinces.

Date Selection

Available dates are dynamically loaded from the Sentinel Hub Catalog API (with OData fallback), showing all dates with Sentinel-5P observations over Iraq for the current month.

Iraqi Governorates

All 18 governorates are included: Baghdad, Basra, Nineveh, Erbil, Sulaymaniyah, Duhok, Kirkuk, Diyala, Anbar, Babel, Karbala, Najaf, Wasit, Maysan, Dhi Qar, Muthanna, Qadisiyyah, Saladin.

Tech Stack

• React 18/19 + TypeScript
• Mapbox GL + react-map-gl (map rendering)
• date-fns (date formatting)
• tsup (library bundling)
• Tailwind CSS v4 (dev environment styling)

License

MIT