geodesic.boson.dataset.Dataset.share_as_stac_service#

Dataset.share_as_stac_service(alias=None, description=None, ttl=None, pin_version=False, referer_allowlist=None, referer_blocklist=None, extra_settings={}, create_new=False)#

Share a dataset as a OGC API: Features service or STAC API, depending on the dataset.

Parameters:

  • alias (str | None) – An optional alias/nickname for the token. This is used to help users identify and find tokens in their token list. If not provided, a default alias will be used.

  • description (str | None) – An optional description of the token. This is used to help users understand the token’s purpose and usage context. If not provided, a default description will be used.

  • ttl (timedelta | int | float | None) – The time until the dataset’s token should expire. Can be either a timedelta object or an integer/float representing seconds. Defaults to -1 (no expiration) if not provided. Use this for temporary access or testing scenarios.

  • pin_version (bool) – If True, will pin the version of the dataset to the token. This means that the token will always return the same version of the dataset, even if the dataset is updated or modified. Useful for ensuring consistency in production environments.

  • referer_allowlist (list | None) – A list of allowed referer URLs for the token. If set, only HTTP requests from these referers will be allowed to access the service. The ‘Referer’ header is checked using exact prefix matching.

  • referer_blocklist (list | None) – A list of blocked referer URLs for the token. If set, HTTP requests from these referers will be denied access to the service. The ‘Referer’ header is checked using exact prefix matching.

  • create_new (bool) – If True, will create a new token even if one already exists with the same parameters. If ttl is greater than 0, this will always create a new token regardless of this setting.

  • extra_settings (dict) – A dictionary of additional settings to pass to scope this token. This is an advanced parameter - only use if you need specific token configurations not covered by other parameters.

Raises:

requests.HTTPError – If the user is not permitted to access the dataset or if an error occurred

Returns:

a share token and its corresponding data

Return type:

Token

Examples

>>> # Basic OGC API: Features service sharing for 1 hour
>>> uscb_data = geodesic.get_datasets(search='uscb-pop-centers')[0]
>>> token = uscb_data.share_as_ogc_api_features(
...     alias="Population Centers API",
...     description="OGC API: Features service for population data access",
...     ttl=3600
... )
>>> api_url = token.get_ogc_api_features_url()

>>> # Share with security restrictions for API access
>>> import datetime
>>> secure_token = uscb_data.share_as_ogc_api_features(
...     alias="Secure Features API",
...     description="Restricted OGC API access for partner applications",
...     ttl=datetime.timedelta(days=1),
...     pin_version=True,
...     referer_allowlist=["https://partner-app.com", "https://api.partner-app.com"],
...     referer_blocklist=["https://blocked-domain.com"]
... )

>>> # Create persistent API service for production applications
>>> production_token = uscb_data.share_as_ogc_api_features(
...     alias="Production Features API",
...     description="Long-term OGC API: Features service for production applications",
...     pin_version=True
... )  # No TTL for permanent access