Skip to content

Commit e79505c

Browse files
pantierrapantierra
committed
feat: added charter source.
1 parent a22ae57 commit e79505c

14 files changed

Lines changed: 1279 additions & 4 deletions

‎docs/model/sources/Charter/README.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# International Charter on Space and Major Disasters
2+
3+
The International Charter on Space and Major Disasters coordinates satellite data delivery for disaster response worldwide. Charter activations provide satellite imagery and analysis products to assist civil protection authorities.
4+
5+
## Collections
6+
7+
Charter data maps to three Monty collections:
8+
9+
- **Name**: International Charter - Events
10+
- **Code**: `charter-events`
11+
- **Source organisation**: International Charter on Space and Major Disasters
12+
- **Source organisation code**: CHARTER
13+
- **Source URL**: <https://disasterscharter.org>
14+
- **STAC Catalog**: <https://supervisor.disasterscharter.org/api/>
15+
- **Data License**: Charter Activation Data License (public for Events/Hazards; partner access for Response)
16+
- **Source for**: event, hazard, response
17+
- **Temporal Coverage**: 2000-11-05 onwards (Charter formation)
18+
19+
## Data Access
20+
21+
### API Endpoints
22+
23+
```bash
24+
# Activation (Event source) - use direct pattern
25+
https://supervisor.disasterscharter.org/api/activations/act-{activationID}
26+
27+
# Example: Multi-hazard (flood + landslide) in Brazil
28+
curl -s https://supervisor.disasterscharter.org/api/activations/act-1019 | jq
29+
30+
# Area (Hazard source) - links from activations work
31+
https://supervisor.disasterscharter.org/api/activations/act-{id}/areas/{area_slug}.json
32+
```
33+
34+
> [!IMPORTANT]
35+
> Known API quirks:
36+
> - Calls/Activations catalog endpoints are slow (dynamically generated)
37+
> - Activation catalog `self` links point to `.json` suffix but return HTTP 500 - omit suffix
38+
> - Direct activation pattern above is reliable
39+
> - Area links from activation items work correctly
40+
41+
**Alternative browsing**: [STAC Index](https://stacindex.org/catalogs/disasters-charter-mapper-catalog)
42+
43+
### Discover Available Fields
44+
45+
Audit upstream `properties` keys across activation range (requires [jq](https://jqlang.github.io/jq/)):
46+
47+
```bash
48+
for i in $(seq 900 1020); do
49+
curl -s --max-time 5 "https://supervisor.disasterscharter.org/api/activations/act-$i" \
50+
| jq -r '.properties | keys[]?' 2>/dev/null
51+
done | sort -u
52+
```
53+
54+
## Entity Mapping
55+
56+
| Charter Entity | Monty Type | ID Pattern | Collection | Status |
57+
|----------------|------------|------------|------------|--------|
58+
| Activation | Event | `charter-event-{activation_id}` | `charter-events` | ✅ Ready |
59+
| Area (AoI) | Hazard | `charter-hazard-{activation_id}-{area_slug}-{type}` | `charter-hazards` | ✅ Ready |
60+
| Acquisition/Dataset/VAP | Response | `charter-response-{activation_id}-*` | `charter-response` | ⚠️ S3 access TBD |
61+
62+
63+
64+
### Activation → Event
65+
66+
| Charter Field | Monty Field | Notes |
67+
|--------------|-------------|-------|
68+
| `id: "act-1019"` | `id: "charter-event-1019"` | Prefix with `charter-event-` |
69+
| — | `collection: "charter-events"` | **Required** for STAC compliance |
70+
| `properties["
71+
disaster:type"]` | `monty:hazard_codes` | Map via [hazard codes table](#hazard-codes), apply `hazard_profiles.get_canonical_hazard_codes()` |
72+
| `properties["disaster:country"]` | `monty:country_codes[0]` | Already ISO 3166-1 alpha-3 |
73+
| `properties.title` | `title` | Direct copy |
74+
| `properties.datetime` | `datetime` | Event onset time |
75+
| `geometry` (Point) | `geometry` | Direct copy |
76+
| `links[rel=self]` | `links[rel=via]` | Source reference |
77+
78+
> [!IMPORTANT]
79+
> **Onset datetime**: Use `properties.datetime` as the canonical event time. This field equals `properties.created` and matches the embedded `<disasterDate>` in `cpe:cos2_xml`. Do **not** use `properties.updated` - it reflects processing close date (often weeks later).
80+
81+
**Multi-hazard events**: If `disaster:type: ["flood", "landslide"]`, include all hazard codes in the Event item (e.g., both MH0600/FL/nat-hyd-flo-flo and MH0901/LS/nat-geo-mmd-lan).
82+
83+
**Correlation ID**: Generate using standard Monty algorithm from event time, ISO3 country, primary hazard, spatial block, and episode - not Charter `activation_id`.
84+
85+
### Area → Hazard
86+
87+
| Charter Field | Monty Field | Notes |
88+
|--------------|-------------|-------|
89+
| Area `id` | `id` | Pattern: `charter-hazard-{activation_id}-{area_slug}-{type}` |
90+
| — | `collection: "charter-hazards"` | **Required** for STAC compliance |
91+
| `geometry` (Polygon) | `geometry` | Full AoI polygon |
92+
| `properties["disaster:type"]` | `monty:hazard_codes` | **One code per item** (see multi-hazard note below) |
93+
| `properties.title` | `title` | Area name (e.g., "Juiz de Fora") |
94+
| `properties.datetime` | `datetime` | Inherit from parent Activation |
95+
| `properties.description` | `monty:hazard_detail`, `charter:area_priority` | Parse radius and priority from description text |
96+
| Parent Activation | `links[rel=derived_from]` | Link to parent Event: `../charter-events/charter-event-{id}.json` |
97+
98+
> [!IMPORTANT]
99+
> **Multi-hazard strategy**: Create **one Hazard item per disaster type** (following GDACS precedent). For an Area with `disaster:type: ["flood", "landslide"]`:
100+
> - `charter-hazard-1019-juiz-de-fora-flood` with codes MH0600, FL, nat-hyd-flo-flo
101+
> - `charter-hazard-1019-juiz-de-fora-landslide` with codes MH0901, LS, nat-geo-mmd-lan
102+
>
103+
> Same geometry, different `monty:hazard_codes`. This satisfies the Monty schema requirement of exactly one UNDRR-ISC 2025 code per Hazard item.
104+
105+
#### Hazard Detail
106+
107+
Parse Area `description` field for severity and metadata:
108+
109+
| Pattern | Monty Field | Example |
110+
|---------|-------------|---------|
111+
| `Radius (km): X` | `monty:hazard_detail.severity_value: X` | `8` |
112+
| `Radius (km): X` | `monty:hazard_detail.severity_unit: "km"` | `"km"` |
113+
| `Radius (km): X` | `monty:hazard_detail.severity_label: "Area radius"` | `"Area radius"` |
114+
| `Priority: N` | `charter:area_priority: N` | `1` (not a severity metric) |
115+
116+
**CPE Status Mapping**: Charter Areas may include `cpe:status.stage` field. Map to `monty:hazard_detail.estimate_type`:
117+
118+
| CPE Stage | Estimate Type | Notes |
119+
|-----------|---------------|-------|
120+
| `notificationNew` | `primary` | First-pass AoI / notification phase |
121+
| `readyToDeliver` | `secondary` | Delivered-handoff items |
122+
| `readyToArchive` | `secondary` | Archived items |
123+
| *(unknown)* | `primary` | Default for unrecognized stages |
124+
125+
This is an interim mapping pending full CPE stage documentation.
126+
127+
### Response Items
128+
129+
**Source**: Acquisition, Dataset, and Value-Added Product (VAP) items in Charter catalog
130+
**Status**: ⚠️ Requires S3 access or partner credentials - implementation pending
131+
132+
Response items will link to parent Event/Hazard via `monty:corr_id`. Contact Zachary Foltz (zachary.foltz@acri-st.fr) for access details.
133+
134+
## Hazard Codes
135+
136+
Charter `disaster:type` values map to Monty hazard codes:
137+
138+
| Charter Type | UNDRR-ISC 2025 | GLIDE | EM-DAT | Notes |
139+
|--------------|----------------|-------|---------|-------|
140+
| flood | MH0600 | FL | nat-hyd-flo-flo | Flooding (refine to MH0603/MH0604 if flash/riverine) |
141+
| fire | MH1301 | WF | nat-cli-wil-for | Wildfire / forest fire |
142+
| earthquake | GH0101 | EQ | nat-geo-ear-gro | Ground shaking |
143+
| volcano | GH0201 | VO | nat-geo-vol | Volcanic eruption |
144+
| storm_hurricane | MH0400 | ST | nat-met-sto | Generic storm (refine to MH0403 if tropical) |
145+
| cyclone | MH0403 | TC | nat-met-sto-tro | Tropical cyclone |
146+
| tsunami | GH0301 | TS | nat-geo-ear-tsu | |
147+
| landslide | MH0901 | LS | nat-geo-mmd-lan | |
148+
| snow_hazard | MH1202 | SW | nat-met-ext-col | Snow/winter hazard |
149+
| ice | MH0801 | CW | nat-met-ext-col | Ice storm/icing |
150+
| oil_spill | TH0300 | — | tec-ind-che | Chemical spill (technological) |
151+
| explosive_event | TH0600 | — | tec-ind-exp | Explosion (technological) |
152+
| other | — | OT | — | Requires manual review - no UNDRR code |
153+
154+
**Deprecated types** (older activations):
155+
- `storm_hurricane_rural`, `storm_hurricane_urban` → map as `storm_hurricane`
156+
- `flood_large` → MH0604, `flood_flash` → MH0603
157+
158+
> [!NOTE]
159+
> - UNDRR-ISC 2025 code is **required** for Hazard items (exactly one per item)
160+
> - GLIDE and EM-DAT codes are optional but recommended for interoperability
161+
> - `other` has no UNDRR code - manual review required before producing Hazard item
162+
> - Deprecated types (`storm_hurricane_rural`, `flood_large`, etc.) mapped in CSV
163+
> - Apply `hazard_profiles.get_canonical_hazard_codes()` after mapping for standard format
164+
165+
## Implementation Guide
166+
167+
### Step 1: Fetch and Map Activation
168+
169+
```bash
170+
# Fetch activation
171+
curl -s https://supervisor.disasterscharter.org/api/activations/act-1019 > act-1019.json
172+
173+
# Extract fields
174+
cat act-1019.json | jq '{
175+
activation_id: .properties["disaster:activation_id"],
176+
types: .properties["disaster:type"],
177+
country: .properties["disaster:country"],
178+
datetime: .properties.datetime,
179+
geometry: .geometry
180+
}'
181+
```
182+
183+
Create Event item:
184+
185+
```json
186+
{
187+
"stac_version": "1.0.0",
188+
"stac_extensions": ["https://ifrcgo.org/monty-stac-extension/v1.1.0/schema.json"],
189+
"type": "Feature",
190+
"id": "charter-event-1019",
191+
"collection": "charter-events",
192+
"geometry": {"type": "Point", "coordinates": [-43.202, -21.547]},
193+
"properties": {
194+
"title": "[Act-1019/Call-1166] Flood in Brazil",
195+
"datetime": "2026-02-24T17:09:00Z",
196+
"monty:country_codes": ["BRA"],
197+
"monty:hazard_codes": ["MH0600", "FL", "nat-hyd-flo-flo", "MH0901", "LS", "nat-geo-mmd-lan"],
198+
"monty:corr_id": "20260224T170900-BRA-HM-FLOOD-001-GCDB",
199+
"roles": ["event", "source"]
200+
},
201+
"links": [
202+
{"rel": "via", "href": "https://supervisor.disasterscharter.org/api/activations/act-1019"}
203+
]
204+
}
205+
```
206+
207+
### Step 2: Fetch and Map Areas
208+
209+
```bash
210+
# Extract area links
211+
cat act-1019.json | jq -r '.links[] |
212+
select(.rel == "related" and .title | startswith("[Area]")) |
213+
.href'
214+
215+
# Fetch area
216+
curl -s "https://supervisor.disasterscharter.org/api/activations/act-1019/areas/Juiz_de_Fora-QVwJEJDB0IZNzAO3SVGtOw__.json" > area.json
217+
```
218+
219+
Create Hazard item (one per disaster type):
220+
221+
```json
222+
{
223+
"stac_version": "1.0.0",
224+
"stac_extensions": ["https://ifrcgo.org/monty-stac-extension/v1.1.0/schema.json"],
225+
"type": "Feature",
226+
"id": "charter-hazard-1019-juiz-de-fora-flood",
227+
"collection": "charter-hazards",
228+
"geometry": {"type": "Polygon", "coordinates": [[[-43.3, -21.6], ...]]},
229+
"properties": {
230+
"title": "Juiz de Fora",
231+
"datetime": "2026-02-24T17:09:00Z",
232+
"monty:country_codes": ["BRA"],
233+
"monty:hazard_codes": ["MH0600", "FL", "nat-hyd-flo-flo"],
234+
"monty:corr_id": "20260224T170900-BRA-HM-FLOOD-001-GCDB",
235+
"monty:hazard_detail": {
236+
"severity_value": 8,
237+
"severity_unit": "km",
238+
"severity_label": "Area radius"
239+
},
240+
"charter:area_priority": 1,
241+
"roles": ["hazard", "source"]
242+
},
243+
"links": [
244+
{"rel": "derived_from", "href": "../charter-events/charter-event-1019.json"}
245+
]
246+
}
247+
```
248+
249+
### Step 3: Validate
250+
251+
```bash
252+
npm run check-examples
253+
```
254+
255+
## Examples
256+
257+
| Activation | Type | Country | Date | Files |
258+
|------------|------|---------|------|-------|
259+
| Act-896 | Earthquake | ECU | Apr 2016 | [charter-event-896.json](../../../../examples/charter-events/charter-event-896.json) |
260+
| Act-1019 | Flood + Landslide | BRA | Feb 2026 | Multi-hazard example (implementation reference) |
261+
262+
## Reference Files
263+
264+
Upstream data examples (actual Charter API responses):
265+
- [act-1000-activation.json](./act-1000-activation.json) - Single hazard activation (earthquake)
266+
- [act-1000-area-epi.json](./act-1000-area-epi.json) - Earthquake area example
267+
- [act-1019-activation.json](./act-1019-activation.json) - Multi-hazard activation (flood + landslide)
268+
- [act-1019-area-juiz-de-fora.json](./act-1019-area-juiz-de-fora.json) - Flood area example
269+
270+
## Resources
271+
272+
- [International Charter Website](https://disasterscharter.org/)
273+
- [STAC Index - Charter Catalog](https://stacindex.org/catalogs/disasters-charter-mapper-catalog)
274+
- [Disaster STAC Extension](https://github.com/Terradue/stac-extensions-disaster)
275+
- [Monty STAC Extension Spec](../../../../README.md)

0 commit comments

Comments
 (0)