pygeoapi

Common errors

• ModuleNotFoundError: No module named 'setuptools'

  cause The `setuptools` package, while often pre-installed, is not part of the Python standard library and might be missing in minimal Python environments.
  fix Install `setuptools` explicitly: `pip install setuptools`.

• pygeoapi server fails to start (e.g., 'Configuration file not found' or similar error messages related to config paths).

  cause The `PYGEOAPI_CONFIG` environment variable is not set or points to a non-existent configuration file.
  fix Ensure `PYGEOAPI_CONFIG` is set to the correct absolute path of your `pygeoapi-config.yml` file before running `pygeoapi serve`. Example: `export PYGEOAPI_CONFIG=$(pwd)/pygeoapi-config.yml`.

• InvalidParameterValue: Invalid format

  cause The client (e.g., web browser, curl) is making a request without specifying an acceptable format via the `f=` parameter or the `Accept` HTTP header, and pygeoapi cannot determine the preferred output.
  fix Append `?f=json` or `?f=html` to your API endpoint URL, or set the `Accept` HTTP header to `application/json` or `text/html`.

• Errors related to SQLite extensions or `spatialite` on macOS, especially when using `pyenv`.

  cause Incompatibilities or missing dependencies for SQLite spatial extensions when Python is managed by `pyenv` on macOS.
  fix Follow the specific instructions in the pygeoapi documentation for 'Working with Spatialite on OSX' which often involves ensuring Homebrew and pyenv play nicely together and proper installation of `spatialite`.

Warnings

• breaking pygeoapi 0.22.0 and later require Python 3.12 or newer. Older versions might support earlier Python 3 releases.
  Fix: Ensure your environment uses Python 3.12+. Upgrade Python if necessary or use an older pygeoapi version.
• gotcha YAML configuration files are central to pygeoapi and are highly sensitive to indentation. Incorrect spacing or syntax will prevent the server from starting.
  Fix: Carefully review YAML syntax, especially indentation. Use a YAML linter (e.g., `yamllint`) or a text editor with YAML support to validate your `pygeoapi-config.yml` file.
• gotcha When running pygeoapi directly (not via Docker), the `PYGEOAPI_CONFIG` and `PYGEOAPI_OPENAPI` environment variables must be set to the absolute paths of your configuration and OpenAPI definition files, respectively.
  Fix: Before running `pygeoapi serve`, ensure `export PYGEOAPI_CONFIG=/path/to/pygeoapi-config.yml` and `export PYGEOAPI_OPENAPI=/path/to/pygeoapi-openapi.yml` are correctly set in your shell.
• gotcha Specific data provider dependencies (e.g., for PostGIS, Elasticsearch, or GDAL/OGR) are not automatically installed with `pip install pygeoapi`. You must install these separately if your configuration uses them.
  Fix: Identify which providers you are using in your `pygeoapi-config.yml`. Consult the pygeoapi documentation for specific provider requirements and install the necessary Python packages (e.g., `pip install psycopg2-binary` for PostGIS).
• gotcha Clients (browsers, `curl`) sometimes receive an 'Invalid format' or 'InvalidParameterValue' error if the `Accept` header is not properly set or the `f=` parameter is missing in the URL.
  Fix: Explicitly request the desired format by adding `f=json` or `f=html` to your URL (e.g., `http://localhost:5000/collections/obs/items?f=json`) or set the `Accept` HTTP header. Browsers usually handle `text/html` correctly.

Install

• pip install pygeoapi Install stable release

Imports

• BaseProvider

  from pygeoapi.provider.base import BaseProvider

  Used for developing custom data providers.
• API

  from pygeoapi.api import API

  Core API class, mainly used internally or for advanced customizations.

Quickstart

This quickstart generates a basic `pygeoapi-config.yml` file and provides instructions on how to set the necessary environment variables (`PYGEOAPI_CONFIG`, `PYGEOAPI_OPENAPI`), generate the OpenAPI document, and start the pygeoapi server. Users can then access the API through a web browser or programmatic clients.

import os
import yaml

# Define a minimal pygeoapi configuration
config_content = {
    'server': {
        'bind': {'host': '0.0.0.0', 'port': 5000},
        'url': 'http://localhost:5000/',
        'pretty_print': True
    },
    'logging': {
        'level': 'DEBUG'
    },
    'metadata': {
        'identification': {
            'title': 'My pygeoapi instance',
            'abstract': 'A minimal pygeoapi setup.',
            'keywords': ['geospatial', 'API', 'OGC'],
            'license': {'url': 'https://creativecommons.org/licenses/by/4.0/'}
        },
        'provider': {
            'name': 'pygeoapi',
            'url': 'https://pygeoapi.io/'
        }
    },
    'resources': {
        # Add sample data as needed. E.g., a GeoJSON file
        # 'data': {
        #     'type': 'collection',
        #     'title': 'Sample GeoJSON Data',
        #     'description': 'A sample collection from a GeoJSON file.',
        #     'keywords': ['geojson', 'sample'],
        #     'extents': {
        #         'spatial': {'bbox': [-180, -90, 180, 90]},
        #         'temporal': {'interval': ['1900-01-01T00:00:00Z', '2099-12-31T23:59:59Z']}
        #     },
        #     'provider': {
        #         'type': 'feature',
        #         'name': 'GeoJSON',
        #         'data': 'path/to/your/data.geojson'
        #     }
        # }
    }
}

config_file_path = 'pygeoapi-config.yml'
openapi_file_path = 'pygeoapi-openapi.yml'

with open(config_file_path, 'w') as f:
    yaml.dump(config_content, f, sort_keys=False)

print(f"Generated minimal configuration file: {config_file_path}")
print(f"\nTo run pygeoapi:")
print(f"1. Set the configuration environment variable: ")
print(f"   export PYGEOAPI_CONFIG={config_file_path}")
print(f"2. Generate the OpenAPI document (required for server startup):")
print(f"   pygeoapi openapi generate $PYGEOAPI_CONFIG --output-file {openapi_file_path}")
print(f"3. Set the OpenAPI environment variable: ")
print(f"   export PYGEOAPI_OPENAPI={openapi_file_path}")
print(f"4. Start the server:")
print(f"   pygeoapi serve")
print(f"\nAccess your pygeoapi instance at http://localhost:5000 in your browser.")