DOCSEARCHbyAlgolia
Submit Docs

pygeoapi Documentation

repository·master·Indexed 20 days ago

https://github.com/geopython/pygeoapi

A Python server implementation of the OGC API standards suite for deploying RESTful geospatial API endpoints using OpenAPI, GeoJSON, and HTML. Includes guides on Docker deployment, server configuration, OGR provider setup, Admin API management, and OpenAPI document generation.

Tokens
43K
Snippets
146
Records
191
Agent score
67%

What's inside pygeoapi

  1. Overview of pygeoapi

    master
    pygeoapi is a Python-based server implementation of the OGC API suite of standards. It allows organizations to deploy RESTful OGC API endpoints using OpenAPI, GeoJSON, and HTML. It is built on a plugin framework, making it flexible for custom data connections, formats, and processes. It supports multiple Python web frameworks, including Flask (default) and Starlette, and supports asynchronous processing for job management.

  2. Overview of publishing in pygeoapi

    master

    pygeoapi allows you to integrate and publish various geospatial assets through a plugin-based architecture. You can publish:

    • Data: Vector and coverage data, including filesystems, databases, and cloud storage.
    • Metadata: Geospatial metadata (data about data) using standards like STAC or OGC API - Records.
    • Processes: Executable workflows via the OGC API - Processes standard.

    The system relies on a plugin framework for data providers, metadata providers, and processes. For developers looking to extend these capabilities, refer to the custom plugin documentation.

  3. Publishing files to a SpatioTemporal Asset Catalog (STAC)

    master

    The SpatioTemporal Asset Catalog (STAC) is a specification for standardizing geospatial asset metadata (e.g., satellite imagery, LiDAR, vector data, etc.) to enable structured querying based on place and time.

    pygeoapi includes built-in providers that allow users to browse and interact with STAC catalogs. This enables the discovery and access of spatiotemporal assets through standardized interfaces.

  4. Key Features and Capabilities of pygeoapi

    master

    pygeoapi offers several out-of-the-box capabilities for geospatial data serving:

    • Data Providers: Includes plugins for rasterio, GDAL/OGR, Elasticsearch, and PostgreSQL/PostGIS.
    • Output Formats: Supports JSON, GeoJSON, HTML, and CSV.
    • Querying: Supports data filtering via spatial, temporal, or attribute queries.
    • Documentation: Provides OpenAPI / Swagger documentation for developers.
    • Configuration: Uses simple YAML configuration files.
    • Deployment: Can be installed via pip or git, and deployed using UbuntuGIS or the official Docker image.

  5. Overview of pygeoapi plugin architecture

    master

    pygeoapi uses a plugin architecture to extend its functionality across several subsystems. Developers can implement custom logic for data providers, output formats, processes, and the process manager. The core plugin registry is located at pygeoapi.plugin.PLUGINS.

    Each plugin type must implement a specific base class to satisfy the API contract:

    • Data Providers:
      • features/records/maps: pygeoapi.provider.base.BaseProvider
      • edr: pygeoapi.provider.base_edr.BaseEDRProvider
      • tiles: pygeoapi.provider.tile.BaseTileProvider
    • Output Formats: pygeoapi.formatter.base.BaseFormatter
    • Processes: pygeoapi.process.base.BaseProcessor
    • Process Manager: pygeoapi.process.manager.base.BaseManager

  6. Handle process responses (Raw vs Document)

    master

    pygeoapi handles process outputs in two primary ways via the response parameter in the execution request:

    1. Raw (Default): Returns the response in its native encoding and media type as defined by the plugin. Use response: raw (or omit the parameter) to achieve this.
    2. Document: Returns a JSON-encoded response that embeds the resulting payload (binary data may be Base64 encoded). Use response: document to achieve this.

  7. Understand pygeoapi security and access control

    master

    By design, pygeoapi does not include built-in support for authentication or authorization. It does not manage user roles, groups, or fine-grained access control (e.g., restricting access to specific collections or processes) internally.

    To implement security, you must use an external framework or a third-party project designed to run atop pygeoapi. Depending on your requirements, you can implement anything from simple HTTP Basic Authentication to complex access control models.

  9. Configure CRS and Bounding Box defaults for OGC API - Maps

    master

    When requesting maps via OGC API - Maps, the following CRS and Bounding Box behaviors apply:

    Coordinate Reference Systems (CRS): Supported formats include URIs or CURIEs:

    • http://www.opengis.net/def/crs/EPSG/0/4326
    • [EPSG:4326]
    • EPSG:4326 (unsafe)
    • CRS:84 (unsafe)
    • OGC:CRS84 (unsafe)

    Defaults:

    • If crs is not provided, the server defaults to storage_crs. If storage_crs is missing, it defaults to CRS84.
    • If crs-bbox is not provided, it defaults to CRS84.
    • If bbox is not provided, it defaults to -180, -90, 180, 90.

    Response Headers: Every response includes Content-Crs and Content-Bbox headers.

  10. Create hierarchical collections

    master

    By default, all collections are published at /collections. You can create a hierarchy by using slashes in the resource key within the resources section.

    Example:

    resources:
  naturalearth/lakes:
    ...

    This makes the collection available at /collections/naturalearth/lakes.

    Note: Currently, pygeoapi does not support collection grouping. Navigating to the parent path (e.g., /collections/naturalearth) will not provide an aggregate list of sub-collections.

  11. Supported OGC API Standards in pygeoapi

    master

    pygeoapi provides varying levels of support for OGC standards. It acts as a Reference Implementation for several key standards, meaning it serves as a primary example of how the standard should be implemented.

    Reference Implementations:

    • OGC API - Features
    • OGC API - Tiles
    • OGC API - Environmental Data Retrieval

    Compliant Standards:

    • OGC API - Processes

    Implemented Standards:

    • OGC API - Coverages
    • OGC API - Maps
    • OGC API - Records
    • SpatioTemporal Asset Catalog (STAC)

  12. How the HATEOAS STAC Provider works

    master

    The Hateoas provider implements a REST application where clients navigate resources via hypermedia links. This requires a specific directory structure and link format to ensure the catalog can be moved or copied without breaking.

    Link Rules

    • Structural links (root, parent, child, item, collection) must use relative URLs.
    • Asset links must use absolute URLs.
    • No self link should be used (as it would require an absolute URL).

    Directory Structure Rules

    1. Root documents: Catalogs must be named catalog.json; Collections must be named collection.json.
    2. Hierarchy: Sub-Catalogs/Collections must be in subdirectories (max 1 level deeper than the parent document).
    3. Items: Must be named <id>.json and stored in a unique subdirectory named after the <id> (e.g., item_id/item_id.json).
    4. Consistency: Use structural elements (Catalog/Collection) consistently across hierarchy levels.
    // Example catalog.json structure
{
    "id": "STAC-Catalog",
    "type": "Catalog",
    "stac_version": "1.0.0",
    "links": [
        { "rel": "root", "href": "./catalog.json", "type": "application/json" },
        { "rel": "child", "href": "./eo4ce/catalog.json", "type": "application/json" }
    ]
}