diff --git a/README.md b/README.md index bf65d0e..7ac740e 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,18 @@ -# Template Extension Specification +# Earthquake Extension Specification -- **Title:** Template -- **Identifier:** -- **Field Name Prefix:** template +- **Title:** Earthquake +- **Identifier:** +- **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 index 2472ecc..9b2a4dc 100644 --- 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 index cf19370..fc86845 100644 --- 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" } } -} +} \ No newline at end of file