initial earthquake extension with examples

stac-extensions · Jun 18, 2024 · dd15da8 · dd15da8
1 parent 85e1681
commit dd15da8
Show file tree

Hide file tree

Showing 3 changed files with 167 additions and 97 deletions.
diff --git a/README.md b/README.md
@@ -1,14 +1,18 @@
-# Template Extension Specification
+# Earthquake Extension Specification
 
-- **Title:** Template
-- **Identifier:** <https://stac-extensions.github.io/template/v1.0.0/schema.json>
-- **Field Name Prefix:** template
+- **Title:** Earthquake
+- **Identifier:** <https://stac-extensions.github.io/earthquake/v1.0.0/schema.json>
+- **Field Name Prefix:** eq
 - **Scope:** Item, Collection
 - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Proposal
-- **Owner**: @your-gh-handles @person2
+- **Owner**: @emmanuelmathot @fabricebrito
 
-This document explains the Template Extension to the [SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification.
-This is the place to add a short introduction.
+This document explains the Earthquake Extension to the [SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification.
+The specification is largely inspired by the existing earthquakes catalogs such as
+the [USGS Earthquake Hazards Program](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) and
+the [European-Mediterranean Seismological Centre](https://www.emsc-csem.org/).
+
+A specific [section](#mappings-with-existing-catalogs) gives the translation between the existing data models and the STAC model.
 
 - Examples:
   - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item
@@ -21,41 +25,108 @@ This is the place to add a short introduction.
 The fields in the table below can be used in these parts of STAC documents:
 
 - [ ] Catalogs
-- [x] Collections
+- [ ] Collections
 - [x] Item Properties (incl. Summaries in Collections)
-- [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
+- [ ] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
 - [ ] Links
 
-| Field Name           | Type                      | Description                                  |
-| -------------------- | ------------------------- | -------------------------------------------- |
-| template:new_field   | string                    | **REQUIRED**. Describe the required field... |
-| template:xyz         | [XYZ Object](#xyz-object) | Describe the field...                        |
-| template:another_one | \[number]                 | Describe the field...                        |
+| Field Name        | Type                          | Description                                                                                                                    |
+| ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| eq:magnitude      | \[number]                     | **REQUIRED**. The magnitude for the event. See also magnitude_type.                                                            |
+| eq:magnitude_type | string                        | The type of magnitude. Default to `mw`.                                                                                        |
+| eq:places         | \[string]                     | The list of places referencing locations in relation with the event                                                            |
+| eq:felt           | number                        | The number of felt reports.                                                                                                    |
+| eq:status         | string                        | Indicates whether the event has been reviewed by a human. Possible value: `automatic`, `reviewed`, `deleted`                   |
+| eq:tsunami        | boolean                       | This flag is set to `true` for large events in oceanic regions and `false` otherwise.                                          |
+| eq:sources        | \[[source object](#eqsource)] | **REQUIRED**. A unique identifier for the event. This is the current preferred id for the event, and may change over time, the |
+| eq:depth          | number                        | The depth of the event in kilometers.                                                                                          |
 
 ### Additional Field Information
 
-#### template:new_field
+#### eq:magnitude_type
+
+The `eq:magnitude_type` field is a string that describes the type of magnitude. The default value is `mw` (moment magnitude).
+The complete list of possible values is available [here](https://www.usgs.gov/programs/earthquake-hazards/magnitude-types).
+
+#### eq:places
+
+The `eq:places` field is a list of strings that reference locations in relation with the event.
+It is recommended to use [GeoNames](http://www.geonames.org/) dataset to reference populated places that are in close proximity to a seismic event.
+If there is no nearby city within 300 kilometers (or if the nearby cities database is unavailable for some reason),
+the [Flinn-Engdahl (F-E)](https://www.isc.ac.uk/standards/FEregions/) seismic and geographical regionalization scheme is used.
+
+#### eq:sources
+
+The `eq:sources` field is an object that contains information about the sources that contributed to the event.
+
+| Field Name | Type   | Description                                                                                              |
+| ---------- | ------ | -------------------------------------------------------------------------------------------------------- |
+| name       | string | **REQUIRED**. The name identifying a data contributor in the source catalog                              |
+| code       | string | **REQUIRED**. An identifying code assigned by - and unique from - the corresponding source for the event |
+| catalog    | string | The name of the catalog that the source belongs to. See [Catalogs](#catalogs) for the possible names     |
+
+The order of the sources in the list is important. The first source is considered the preferred source of information for the event.
+For each catalog, one or more links should be provided to the related event items (see [Relation types](#relation-types)).
+
+##### Catalogs
 
-This is a much more detailed description of the field `template:new_field`...
+Several sources are cataloging seismic events. The `catalog` field may be used to reference the catalog that the source belongs to
+so that multiple sources can be linked to the same event.
 
-### XYZ Object
+The following table list the catalogs that are currently identified:
 
-This is the introduction for the purpose and the content of the XYZ Object...
+| Catalog Name | Description                                                                         |
+| ------------ | ----------------------------------------------------------------------------------- |
+| `USGS`       | [USGS Earthquake Hazards Program](https://www.usgs.gov/programs/earthquake-hazards) |
+| `EMSC`       | [European-Mediterranean Seismological Centre](https://www.emsc-csem.org/)           |
+| `FDSN`       | [International Federation of Digital Seismograph Networks](https://www.fdsn.org/)   |
 
-| Field Name | Type   | Description                                  |
-| ---------- | ------ | -------------------------------------------- |
-| x          | number | **REQUIRED**. Describe the required field... |
-| y          | number | **REQUIRED**. Describe the required field... |
-| z          | number | **REQUIRED**. Describe the required field... |
+## Mappings with existing catalogs
+
+### USGS Earthquake GeoJSON Summary Feed
+
+The following table gives the mapping between the fields in the [USGS Earthquake GeoJSON Summary Feed](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) and the STAC model.
+
+| ComCat Field Name                                                    | STAC Field Name      | Description                                                                                                                              |
+| -------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| [title](https://earthquake.usgs.gov/data/comcat/index.php#title)     | `title`              | A brief description of the event.                                                                                                        |
+| [mag](https://earthquake.usgs.gov/data/comcat/index.php#mag)         | `eq:magnitude`       | The magnitude for the event.                                                                                                             |
+| [magType](https://earthquake.usgs.gov/data/comcat/index.php#magType) | `eq:magnitude_type`  | The type of magnitude.                                                                                                                   |
+| [time](https://earthquake.usgs.gov/data/comcat/index.php#time)       | `datetime`           | The time of the event converted from milliseconds since the epoch to ISO8601                                                             |
+| [updated](https://earthquake.usgs.gov/data/comcat/index.php#updated) | `updated`            | The time when the event was last converted transformed to ISO8601                                                                        |
+| [place](https://earthquake.usgs.gov/data/comcat/index.php#place)     | `eq:places`          | The list of places referencing locations in relation with the event                                                                      |
+| [url](https://earthquake.usgs.gov/data/comcat/index.php#url)         | `links`              | The URL to the event page on the USGS website. The link must have the relationship `related` and the mime-type `text/html`               |
+| [detail](https://earthquake.usgs.gov/data/comcat/index.php#detail)   | `links`              | The URL to the event detail page on the USGS website. The link must have the relationship `related` and the mime-type `application/json` |
+| [felt](https://earthquake.usgs.gov/data/comcat/index.php#felt)       | `eq:felt`            | The number of felt reports.                                                                                                              |
+| [status](https://earthquake.usgs.gov/data/comcat/index.php#status)   | `eq:status`          | Indicates whether the event has been reviewed by a human.                                                                                |
+| [tsunami](https://earthquake.usgs.gov/data/comcat/index.php#tsunami) | `eq:tsunami`         | This flag is set to `true` for large events in oceanic regions and `false` otherwise.                                                    |
+| [sig](https://earthquake.usgs.gov/data/comcat/index.php#sig)         | `eq:significance`    | A number describing how significant the event is. Larger numbers indicate a more significant event.                                      |
+| [net](https://earthquake.usgs.gov/data/comcat/index.php#net)         | `eq:sources[0].name` | The network code of the preferred source of information for the event.                                                                   |
+| [code](https://earthquake.usgs.gov/data/comcat/index.php#code)       | `eq:sources[0].code` | The event code of the preferred source of information for the event.                                                                     |
+| [sources](https://earthquake.usgs.gov/data/comcat/index.php#sources) | `eq:sources[*].name` | The network code of the other sources of information for the event.                                                                      |
+| [ids](https://earthquake.usgs.gov/data/comcat/index.php#ids)         | `eq:sources[*].code` | The event code of the other sources of information for the event.                                                                        |
+
+### EMSC Earthquake Catalog
+
+The following table gives the mapping between the fields in the [EMSC FDSN-EVENT web service](https://www.emsc-csem.org/Files/epos/specifications/Specs_fdsnevent-WS.pdf) and the STAC model.
+
+| EMSC Field Name | STAC Field Name | Description |
+| --------------- | --------------- | ----------- |
 
 ## Relation types
 
 The following types should be used as applicable `rel` types in the
 [Link Object](https://github.com/radiantearth/stac-spec/tree/master/item-spec/item-spec.md#link-object).
 
-| Type           | Description                           |
-| -------------- | ------------------------------------- |
-| fancy-rel-type | This link points to a fancy resource. |
+| Type   | Description                                                |
+| ------ | ---------------------------------------------------------- |
+| source | This link points to a source of information for the event. |
+
+### Additional fields
+
+| Field Name | Type   | Description                                                                                                        |
+| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
+| source     | string | The identifier of the source of information for the event. See [`eq:sources.id`](#eqsources) for more information. |
 
 ## Contributing
 

diff --git a/examples/collection.json b/examples/collection.json
@@ -2,12 +2,12 @@
   "stac_version": "1.0.0",
   "stac_extensions": [
     "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json",
-    "https://stac-extensions.github.io/template/v1.0.0/schema.json"
+    "https://stac-extensions.github.io/earthquake/v1.0.0/schema.json"
   ],
   "type": "Collection",
-  "id": "collection",
-  "title": "A title",
-  "description": "A description",
+  "id": "significant-earthquakes-2023",
+  "title": "Significant Earthquakes Archive 2023",
+  "description": "A collection of significant earthquakes that occurred in 2023",
   "license": "Apache-2.0",
   "extent": {
     "spatial": {
@@ -23,41 +23,27 @@
     "temporal": {
       "interval": [
         [
-          "2015-06-23T00:00:00Z",
-          null
+          "2023-01-01T00:00:00Z",
+          "2023-12-31T23:59:59Z"
         ]
       ]
     }
   },
-  "template:new_field": "test",
-  "template:xyz": {
-    "x": 1,
-    "y": 2,
-    "z": 3
-  },
-  "template:another_one": [
-    1,
-    2,
-    3
-  ],
-  "assets": {
-    "example": {
-      "href": "https://example.com/examples/file.xyz",
-      "template:new_field": "test"
-    }
-  },
   "item_assets": {
     "data": {
       "roles": [
         "data"
-      ],
-      "template:new_field": "test"
+      ]
     }
   },
   "summaries": {
     "datetime": {
-      "minimum": "2015-06-23T00:00:00Z",
-      "maximum": "2019-07-10T13:44:56Z"
+      "minimum": "2023-01-01T00:00:00Z",
+      "maximum": "2023-12-31T23:59:59Z"
+    },
+    "eq:magnitude": {
+      "minimum": 5.0,
+      "maximum": 9.2
     }
   },
   "links": [

diff --git a/examples/item.json b/examples/item.json
@@ -1,67 +1,80 @@
 {
   "stac_version": "1.0.0",
   "stac_extensions": [
-    "https://stac-extensions.github.io/template/v1.0.0/schema.json"
+    "https://stac-extensions.github.io/earthquake/v1.0.0/schema.json"
   ],
   "type": "Feature",
   "id": "item",
-  "bbox": [
-    172.9,
-    1.3,
-    173,
-    1.4
-  ],
   "geometry": {
-    "type": "Polygon",
+    "type": "Point",
     "coordinates": [
-      [
-        [
-          172.9,
-          1.3
-        ],
-        [
-          173,
-          1.3
-        ],
-        [
-          173,
-          1.4
-        ],
-        [
-          172.9,
-          1.4
-        ],
-        [
-          172.9,
-          1.3
-        ]
-      ]
+      37.0143,
+      37.2256,
+      10
     ]
   },
   "properties": {
-    "datetime": "2020-12-11T22:38:32Z",
-    "template:new_field": "test",
-    "template:xyz": {
-      "x": 1,
-      "y": 2,
-      "z": 3
-    },
-    "template:another_one": [
-      1,
-      2,
-      3
+    "datetime": "2023-02-06T01:17:34 Z",
+    "title": "M 7.8 - Pazarcik earthquake, Kahramanmaras earthquake sequence",
+    "eq:magnitude": 7.8,
+    "eq:magnitude_type": "mww",
+    "eq:depth": 10,
+    "eq:places": [
+      "Pazarcik",
+      "Kahramanmaras"
+    ],
+    "eq:felt": 2047,
+    "eq:status": "reviewed",
+    "eq:tsunami": false,
+    "eq:sources": [
+      {
+        "name": "us",
+        "code": "us6000jllz",
+        "catalog": "USGS-NEIC"
+      },
+      {
+        "name": "usauto",
+        "code": "usauto6000jllz",
+        "catalog": "USGS-NEIC"
+      },
+      {
+        "name": "at",
+        "code": "at00rpmwxe",
+        "catalog": "USGS-NEIC"
+      },
+      {
+        "name": "pt",
+        "code": "pt22037000",
+        "catalog": "USGS-NEIC"
+      }
     ]
   },
   "links": [
     {
       "href": "https://example.com/examples/item.json",
       "rel": "self"
+    },
+    {
+      "title": "USGS detailed JSON",
+      "href": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us6000jllz&format=geojson",
+      "rel": "source",
+      "type": "application/geo+json"
+    },
+    {
+      "title": "USGS Event Page",
+      "href": "https://earthquake.usgs.gov/earthquakes/eventpage/us6000jllz/executive",
+      "rel": "related",
+      "type": "text/html"
     }
   ],
   "assets": {
     "data": {
-      "href": "https://example.com/examples/file.xyz",
-      "template:new_field": "test"
+      "href": "https://earthquake.usgs.gov/product/internal-moment-tensor/us_6000jllz_mww/us/1675646838040/quakeml.xml",
+      "roles": [
+        "data"
+      ],
+      "title": "QuakeML",
+      "type": "application/xml"
     }
   }
-}
+}