{"id":7562,"library":"pygeoapi","title":"pygeoapi","description":"pygeoapi is a Python server implementation of the OGC API suite of standards. It enables organizations to deploy RESTful OGC API endpoints using OpenAPI, GeoJSON, and HTML. The current version is 0.23.2, with releases happening roughly every 2-3 months.","status":"active","version":"0.23.2","language":"en","source_language":"en","source_url":"https://github.com/geopython/pygeoapi","tags":["geospatial","API","OGC","GIS","web server"],"install":[{"cmd":"pip install pygeoapi","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"Used for developing custom data providers.","symbol":"BaseProvider","correct":"from pygeoapi.provider.base import BaseProvider"},{"note":"Core API class, mainly used internally or for advanced customizations.","symbol":"API","correct":"from pygeoapi.api import API"}],"quickstart":{"code":"import os\nimport yaml\n\n# Define a minimal pygeoapi configuration\nconfig_content = {\n    'server': {\n        'bind': {'host': '0.0.0.0', 'port': 5000},\n        'url': 'http://localhost:5000/',\n        'pretty_print': True\n    },\n    'logging': {\n        'level': 'DEBUG'\n    },\n    'metadata': {\n        'identification': {\n            'title': 'My pygeoapi instance',\n            'abstract': 'A minimal pygeoapi setup.',\n            'keywords': ['geospatial', 'API', 'OGC'],\n            'license': {'url': 'https://creativecommons.org/licenses/by/4.0/'}\n        },\n        'provider': {\n            'name': 'pygeoapi',\n            'url': 'https://pygeoapi.io/'\n        }\n    },\n    'resources': {\n        # Add sample data as needed. E.g., a GeoJSON file\n        # 'data': {\n        #     'type': 'collection',\n        #     'title': 'Sample GeoJSON Data',\n        #     'description': 'A sample collection from a GeoJSON file.',\n        #     'keywords': ['geojson', 'sample'],\n        #     'extents': {\n        #         'spatial': {'bbox': [-180, -90, 180, 90]},\n        #         'temporal': {'interval': ['1900-01-01T00:00:00Z', '2099-12-31T23:59:59Z']}\n        #     },\n        #     'provider': {\n        #         'type': 'feature',\n        #         'name': 'GeoJSON',\n        #         'data': 'path/to/your/data.geojson'\n        #     }\n        # }\n    }\n}\n\nconfig_file_path = 'pygeoapi-config.yml'\nopenapi_file_path = 'pygeoapi-openapi.yml'\n\nwith open(config_file_path, 'w') as f:\n    yaml.dump(config_content, f, sort_keys=False)\n\nprint(f\"Generated minimal configuration file: {config_file_path}\")\nprint(f\"\\nTo run pygeoapi:\")\nprint(f\"1. Set the configuration environment variable: \")\nprint(f\"   export PYGEOAPI_CONFIG={config_file_path}\")\nprint(f\"2. Generate the OpenAPI document (required for server startup):\")\nprint(f\"   pygeoapi openapi generate $PYGEOAPI_CONFIG --output-file {openapi_file_path}\")\nprint(f\"3. Set the OpenAPI environment variable: \")\nprint(f\"   export PYGEOAPI_OPENAPI={openapi_file_path}\")\nprint(f\"4. Start the server:\")\nprint(f\"   pygeoapi serve\")\nprint(f\"\\nAccess your pygeoapi instance at http://localhost:5000 in your browser.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your environment uses Python 3.12+. Upgrade Python if necessary or use an older pygeoapi version.","message":"pygeoapi 0.22.0 and later require Python 3.12 or newer. Older versions might support earlier Python 3 releases.","severity":"breaking","affected_versions":">=0.22.0"},{"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.","message":"YAML configuration files are central to pygeoapi and are highly sensitive to indentation. Incorrect spacing or syntax will prevent the server from starting.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `setuptools` explicitly: `pip install 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.","error":"ModuleNotFoundError: No module named 'setuptools'"},{"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`.","cause":"The `PYGEOAPI_CONFIG` environment variable is not set or points to a non-existent configuration file.","error":"pygeoapi server fails to start (e.g., 'Configuration file not found' or similar error messages related to config paths)."},{"fix":"Append `?f=json` or `?f=html` to your API endpoint URL, or set the `Accept` HTTP header to `application/json` or `text/html`.","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.","error":"InvalidParameterValue: Invalid format"},{"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`.","cause":"Incompatibilities or missing dependencies for SQLite spatial extensions when Python is managed by `pyenv` on macOS.","error":"Errors related to SQLite extensions or `spatialite` on macOS, especially when using `pyenv`."}]}