Spatio‐Temporal Asset Catalogs (STAC)
As of 2.7.1 Geoportal Server implements Spatio-Temporal Asset Catalogs (STAC). The STAC family of specifications aim to standardize the way geospatial asset metadata is structured and queried. A 'spatiotemporal asset' is any file that represents information about the Earth captured in a certain space and time. Geoportal Server 3.0.1 adds various capabilities to its support for STAC.
This page contains information about the support for STAC and the corresponding STAC API in Geoportal Server.
The following are parameters available in app-context.xml that affect the behavior and capabilities for STAC in Geoportal Server. Below the list for 3.0.1:
When supporting STAC, set the app-config.xml property supportsCollections to true.
In geoportalContext the following settings are important when configuring Geoportal Server for STAC:
<beans:bean id="geoportalContext" class="com.esri.geoportal.context.GeoportalContext">
...
<beans:property name="supportsCollections" value="true" />
<beans:property name="geometryService" value="${gpt_geometryService:}" />
...
</beans:bean>
| Parameter Name | Description |
|---|---|
| supportsCollections | Determines whether Geoportal Server is configured to allow assigning metadata content (or STAC items in this case) to collections. true or false. For STAC this must be set to true. |
| geometryService | This property is the URL to an ArcGIS GIS Server Geometry Service https://www.example.com/arcgis/rest/services/Utilities/Geometry/GeometryServer. If this property is set, Geoportal Server's STAC supports projecting STAC geometries between coordinate reference systems (CRS) as well as validate if an STAC Item geometry intersects the STAC Collection geometry (see below). |
When using Geoportal Server to serve STAC, we use a second index in the search engine to store/access information about the STAC Collection objects. The name of this index is set in elasticContext bean in app-context.xml. The two indexes configured here should not have the same name. Upon starting Tomcat, Geoportal Server will check connection to and existence of the two indexes. If either of the indexes is not found, Geoportal Server will attempt to create them. Both indexes use the same mappings file (see /geoportal/WEB-INF/classes/config/elastic-mappings-7.json).
<beans:bean id="elasticContext" class="com.esri.geoportal.lib.elastic.ElasticContextHttp">
...
<beans:property name="indexName" value="${gpt_indexName:metadata}" />
<beans:property name="collectionIndexName" value="${gpt_collectionIndexName:collections}" />
...
| Parameter Name | Description |
|---|---|
| indexName | Name of the index used to store STAC Item objects. |
| collectionIndexName | Name of the index used to store STAC Collection objects. |
In stacContext the following settings are important when configuring Geoportal Server for STAC:
<beans:bean id="stacContext" class="com.esri.geoportal.service.stac.StacContext">
<beans:property name="statusFld" value="${gpt_statusFld:status}"/>
<beans:property name="numStacFeaturesAddItem" value="${gpt_numStacFeaturesAddItem:500}" />
<beans:property name="validateStacFields" value="${gpt_validateStacFields:true}" />
<beans:property name="canStacAutogenerateId" value="${gpt_canStacAutogenerateId:true}" />
<beans:property name="canStacGeomTransform" value="${gpt_canStacGeomTransform:false}" />
<beans:property name="canStacAutogenerateBbox" value="${gpt_canStacAutogenerateBbox:true}" />
<beans:property name="stacBboxSize" value="${gpt_stacBboxSize:0.00001}" />
<beans:property name="geomWKTField" value="${gpt_geomWKTField:}" />
<beans:property name="geomCRSField" value="${gpt_geomCRSField:}" />
<beans:property name="validationRules">
<beans:list>
<beans:value>unique|properties.fieldname</beans:value>
<beans:value>intersects_collection</beans:value>
<beans:value>unique|properties.xom:edp_equip_id</beans:value>
<beans:value>intersects_collection</beans:value>
<beans:value>geometry_source_matches</beans:value>
<beans:value>match_expression |id,^[A-Za-z0-9_-]+$</beans:value>
<beans:value>mandatory_fields|properties.datetime</beans:value>
</beans:list>
</beans:property>
<beans:property name="fieldMappings">
<beans:list>
<beans:value>prefix:stac_property=index_field_with_suffix</beans:value>
</beans:list>
</beans:property>
</beans:bean>
| Parameter Name | Description |
|---|---|
| statusFld | Name of a STAC item properties field used to indicate the status of a STAC item (draft, final or active, inactive or any other status indicator for the specific implementation. |
| numStacFeaturesAddItem | Number of features allowed in FeatureCollection in POST request to prevent service timeout. |
| validateStacFields | Validate feature in POST and PUT request as per https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md. |
| canStacAutogenerateId | If true, Geoportal Server will generate and assign a unique STAC item identifier to a new item as it is being added to the catalog that does not have an id in the STAC item body. If not true, STAC items without an id will be rejected. |
| canStacGeomTransform | If true, Geoportal Server can generate STAC items in coordinate reference systems (CRS) different from the default EPSG:4326. To support geometry transformations, an ArcGIS GIS Server Geometry Service needs to be accessible to the Geoportal Server. |
| canStacAutogenerateBbox | If true, Geoportal Server will generate a bounding box when a STAC item is submitting with a geometry field, but not the associated bbox field. |
| stacBboxSize | When allowing Geoportal Server to generate a bbox for a STAC item, set this value to be the 'radius' of the bbox generated for Point geometries. The bounding coordinates of the bbox will be set this distance away from the submitted Point geometry. For Polyline or Polygon geometries, the stacBboxSize is unused and instead the bbox will be determined based on minimum and maximum bounding coordinates of the geometry. |
| geomWKTField | For some applications, there is the possibility to store one or more geometries of different types in the same STAC item. These geometries are stored a well-known-text (WKT) strings in a STAC item property named based on the geomWKTField value. See the more detailed explanation below. |
| geomCRSField | When submitting/requesting STAC items in CRS different from the default EPSG:4326, the CRS of the request is included in this STAC Item property. |
| validationRules | rule definition string: rule_type ::= <type_unique> | <type_intersects_collection> type_unique ::= 'unique | ' <field1_name>,<field2_name>,...,<fieldN_name> type_intersects_collection ::= 'intersects_collection' type_geometry_source_matches ::= 'geometry_source_matches' type_match_expression ::= match_expression | <field_name>,<reg_expression> type_mandatory_fields ::= mandatory_fields | <field_name1>,<field_name2> |
| fieldMappings | field mapping string: field_mapping ::= stac_field_name=index_field_name stac_field_name=index_field_name ::= name + [_txt | _s | _b | _i | _l | _f | _d | _dt | _cat ] _txt ::= free text field _s ::= keyword field _b ::= boolean field _i ::= integer field _l ::= long field _f ::= float field _d ::= double field _dt ::= date field: e.g. 2025-01-16T11:35:56.732Z _cat ::= hierarchical category field: e.g. continent > country > state/province > county/municipality > city > neighborhood ... |
The Geoportal Server STAC implementation allows for storing multiple geometries for each STAC item. The field defined by geomWKTField is a dictionary of geometries of different type. The allows the following keys: point, multilinestring, polygon, polyhedral. These keys correspond to well-known text [https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry]((WKT) geometry types). The value of each key in the dictionary needs to be WKT encoding of the geometry of the STAC Item.
When submitting a new STAC Item, the client application may submit one or more geometries in WKT. If the client application submits a polyhedral geometry, Geoportal Server will (re)generate a point and polygon geometries (in WKT) from the submitted polyhedral. The point geometry is determined as the average of the x, y, and z coordinates and the polygon as the footprint of the polyhedral. Polyhedrals are useful to represent the geometry of a STAC Item as a box, cylinder or other volumetric shape. Multilinestring geometries are useful to represent geometries in the shape of a T, H, or Y.
The field defined by geomCRSField indicates the CRS used for all geometry fields in the STAC Item. STAC clients may submit STAC Items in different CRS. Geoportal Server transforms the geometries to the internally stored CRS (EPSG:4326) as part of the ingest workflow.
When requesting STAC Items in a CRS different than EPSG:4326 (assuming canStacGeomTransform==true), the return JSON is technically not compliant with the GeoJSON spec (since that limits geometry and bbox fields to EPSG:4326). The ability to submit/request STAC Items with geometries in different CRS is provided as a convenience to STAC client applications.
Example:
"crs": "<CRS identifier here>",
"geometry_wkt": {
"point": {
"wkt": "POINT Z (30 20 8)",
"update_date": "2025-07-02T08:49:17Z"
},
"multilinestring": {
"wkt": "MULTILINESTRING Z ((30 10 0, 10 30 10, 40 40 20))"
"update_date": "2025-07-02T08:49:17Z"
},
"polygon": {
"wkt": "POLYGON Z ((30 10 0, 40 40 10, 20 40 20, 10 20 40, 30 10 0))"
"update_date": "2025-07-02T08:49:17Z"
},
"polyhedral": {
"wkt": "POLYHEDRALSURFACE Z ( PATCHES ((-4.0730481686 ... 5471 3.068316 -17.81317)))",
"update_date": "2025-07-02T08:49:17Z"
}
}
Note that it is possible to drive the STAC settings using environment variables. In order for a value for a configuration setting to be taken from an environment variable, change the beans:property value from the_value to ${environment_variable_name:the_value}. The ${a:b} notation signals the Spring framework to look for the environment variable environment_variable. If it exists (for the account the Tomcat server runs in) then its value will be used, otherwise the value after the colon will be used.
Access the URL at http://servername:8080/geoportal/stac, it will show the STAC API landing page. From here, you can access the collections end point, and dive further into a collection and its items. The implemented STAC API is accessible via the API tab in the Geoportal application.
Geoportal Server implements the base STAC API as well as the transaction API extension. This means creating, updating, deleting, reading, and searching for STAC Items and Collections is all available via Geoportal Server's STAC implementation.
In the API panel, the STAC API is included. Each of the operations (not limited to STAC API) can be used from this page.
Note: If you change the context name of Geoportal Server, make sure to update /geoportal3/api/gpt_api.json and set basePath to the context name of your webapp.
View of the [https://www.example.com/geoportal/#apiPanel](STAC API as included in the API panel):
The STAC Transaction service is secured similar to the Geoportal application itself: http://servername:8080/geoportal/stac/collections/** are secured by Spring oAuth. For simple Authentication, generate token and then append token to request.
1. Generate token ->
POST http://localhost:8080/geoportal/oauth/token
username:
password:
client_id:geoportal-client
grant_type:password\
2. Append token
POST http://localhost:8080/geoportal/stac/collections/{collectionID}/items?access_token=token_generated_above
Populating STAC with Collections and Items uses the STAC API. This RESTful API can be accessed from any scripting language, but so far Python appears the most popular. This in part because ArcGIS Pro is a common environment from where STAC may be populated based on satellite imagery, oriented imagery, feature classes, etc.
The STAC API uses the different HTTP operations (GET, POST, PUT, PATCH, DELETE) for the different operations.
The main organizational element of STAC is the "collection". While STAC does not prescribe how collections are created, consider things that have something in common: a construction project, an asset inspection program, a satellite/drone platform, etc. All STAC Items are part of a (one) collection.
This means that before submitting STAC Items, you will need to create the STAC Collection to Geoportal Server. You have two options for this:
- Use the STAC API.
- Interactively add a collection using the Collections panel (new in Geoportal Server 3.0.1).
STAC items are GeoJSON Feature documents and can be directly published to Geoportal Server. A basic use of Python to publish new STAC Items or update existing ones is as follows:
def add_item(stac_json):
stac_text = json.dumps(stac_json)
result = http.request('POST', f'https://www.example.com/geoportal/stac/collections/example_collection/items', body=stac_text, headers=headers)
return result
def update_item(stac_json):
stac_id = stac_json['id']
stac_text = json.dumps(stac_json)
result = http.request('PUT', f'https://www.example.com/tva/stac/collections/example_collection/items/{stac_id}', body=stac_text, headers=headers)
return result
Adding a new STAC Item happens on the Collections .../items API, while updating a STAC Item happens on the STAC Item API itself.
Notes:
- If you want the thumbnail of the STAC item to show in the Geoportal Server search page, include a field
thumbnail_sin the JSON with a value pointing to the image:"thumbnail_s": "https://www.example.com/image.jpg". - When working with large data files, it is recommended to convert the data to cloud-optimized formats (like COG).