Code documentation

Top level code documentation. Follow link in section for module/class member information

API

Root level code of pygeoapi, parsing content provided by webframework. Returns content from plugins and sets reponses

class pygeoapi.api.API(config)[source]

API object

__init__(config)[source]

constructor

Parameters:config – configuration dict
Returns:pygeoapi.API instance
__weakref__

list of weak references to the object (if defined)

execute_process(headers, args, data, process)[source]

Execute process

Parameters:
  • headers – dict of HTTP headers
  • args – dict of HTTP request parameters
  • data – process data
  • process – name of process
Returns:

tuple of headers, status code, content

get_features(headers, args, dataset)[source]

Queries feature collection

Parameters:
  • headers – dict of HTTP headers
  • args – dict of HTTP request parameters
  • dataset – dataset name
Returns:

tuple of headers, status code, content

pygeoapi.api.FORMATS = ['json', 'html']

Formats allowed for ?f= requests

pygeoapi.api.HEADERS = {'Content-Type': 'application/json', 'X-Powered-By': 'pygeoapi 0.6.0'}

Return headers for requests (e.g:X-Powered-By)

pygeoapi.api._render_j2_template(config, template, data)[source]

render Jinja2 template

Parameters:
  • config – dict of configuration
  • template – template (relative path)
  • data – dict of data
Returns:

string of rendered template

pygeoapi.api.check_format(args, headers)[source]

check format requested from arguments or headers

Parameters:
  • args – dict of request keyword value pairs
  • headers – dict of request headers
Returns:

format value

pygeoapi.api.pre_process(func)[source]

Decorator performing header copy and format checking before sending arguments to mehods

Parameters:func – decorated function
Returns:func
pygeoapi.api.to_json(dict_)[source]

Serialize dict to json

Parameters:dictdict of JSON representation
Returns:JSON string representation

flask_app

Flask module providing the route paths to the api

pygeoapi.flask_app.api()[source]

OpenAPI access point

Returns:HTTP response
pygeoapi.flask_app.api_conformance()[source]

OGC open api conformance access point

Returns:HTTP response
pygeoapi.flask_app.dataset(feature_collection, feature=None)[source]

OGC open api collections/{dataset}/items/{feature} access point

Returns:HTTP response
pygeoapi.flask_app.describe_collections(name=None)[source]

OGC open api collections access point

Parameters:name – identifier of collection name
Returns:HTTP response
pygeoapi.flask_app.describe_processes(name=None)[source]

OGC open api processes access point (experimental)

Parameters:name – identifier of process to describe
Returns:HTTP response
pygeoapi.flask_app.execute_process(name=None)[source]

OGC open api jobs from processes access point (experimental)

Parameters:name – identifier of process to execute
Returns:HTTP response
pygeoapi.flask_app.root()[source]

HTTP root content of pygeopai. Intro page access point

Returns:HTTP response

Logging

Logging system

pygeoapi.log.setup_logger(logging_config)[source]

Setup configuration

Parameters:logging_config – logging specific configuration
Returns:void (creates logging instance)

OpenAPI

pygeoapi.openapi.get_oas(cfg, version='3.0')[source]

Stub to generate OpenAPI Document

Parameters:
  • cfg – configuration object
  • version – version of OpenAPI (default 3.0)
Returns:

OpenAPI definition YAML dict

pygeoapi.openapi.get_oas_30(cfg)[source]

Generates an OpenAPI 3.0 Document

Parameters:cfg – configuration object
Returns:OpenAPI definition YAML dict

Plugins

Note

Please consult section Plugins

Plugin loader

exception pygeoapi.plugin.InvalidPluginError[source]

Bases: Exception

Invalid plugin

__weakref__

list of weak references to the object (if defined)

pygeoapi.plugin.PLUGINS = {'formatter': {'CSV': 'pygeoapi.formatter.csv_.CSVFormatter'}, 'process': {'HelloWorld': 'pygeoapi.process.hello_world.HelloWorldProcessor'}, 'provider': {'CSV': 'pygeoapi.provider.csv_.CSVProvider', 'Elasticsearch': 'pygeoapi.provider.elasticsearch_.ElasticsearchProvider', 'GeoJSON': 'pygeoapi.provider.geojson.GeoJSONProvider', 'GeoPackage': 'pygeoapi.provider.geopackage.GeoPackageProvider', 'OGR': 'pygeoapi.provider.ogr.OGRProvider', 'PostgreSQL': 'pygeoapi.provider.postgresql.PostgreSQLProvider', 'SQLite': 'pygeoapi.provider.sqlite.SQLiteProvider'}}

Loads provider plugins to be used by pygeoapi,formatters and processes available

pygeoapi.plugin.load_plugin(plugin_type, plugin_def)[source]

loads plugin by name

Parameters:
  • plugin_type – type of plugin (provider, formatter)
  • plugin_def – plugin definition
Returns:

plugin object

Utils

Generic util functions used in the code

pygeoapi.util.get_url(scheme, host, port, basepath)[source]

Provides URL of instance

Returns:string of complete baseurl
pygeoapi.util.str2bool(value)[source]

helper function to return Python boolean type (source: https://stackoverflow.com/a/715468)

Parameters:value – value to be evaluated
Returns:bool of whether the value is boolean-ish
pygeoapi.util.yaml_load(fh)[source]

serializes a YAML files into a pyyaml object

Parameters:fh – file handle
Returns:dict representation of YAML

Formatter package

Output formatter package

Base class

class pygeoapi.formatter.base.BaseFormatter(formatter_def)[source]

Bases: object

generic Formatter ABC

__init__(formatter_def)[source]

Initialize object

Parameters:formatter_def – formatter definition
Returns:pygeoapi.providers.base.BaseFormatter
__repr__()[source]

Return repr(self).

__weakref__

list of weak references to the object (if defined)

write(options={}, data=None)[source]

Generate data in specified format

Parameters:
  • options – CSV formatting options
  • data – dict representation of GeoJSON object
Returns:

string representation of format

csv

class pygeoapi.formatter.csv_.CSVFormatter(formatter_def)[source]

Bases: pygeoapi.formatter.base.BaseFormatter

CSV formatter

__init__(formatter_def)[source]

Initialize object

Parameters:formatter_def – formatter definition
Returns:pygeoapi.formatter.csv_.CSVFormatter
__repr__()[source]

Return repr(self).

write(options={}, data=None)[source]

Generate data in CSV format

Parameters:
  • options – CSV formatting options
  • data – dict of GeoJSON data
Returns:

string representation of format

Process package

OGC process package, each process is an independent module

Base class

class pygeoapi.process.base.BaseProcessor(processor_def, process_metadata)[source]

Bases: object

generic Processor ABC. Processes are inherited from this class

__init__(processor_def, process_metadata)[source]

Initialize object :param processor_def: processor definition :returns: pygeoapi.processors.base.BaseProvider

__repr__()[source]

Return repr(self).

__weakref__

list of weak references to the object (if defined)

execute()[source]

execute the process :returns: dict of process response

exception pygeoapi.process.base.ProcessorExecuteError[source]

Bases: Exception

query / backend error

__weakref__

list of weak references to the object (if defined)

hello_world

Hello world example process

class pygeoapi.process.hello_world.HelloWorldProcessor(provider_def)[source]

Bases: pygeoapi.process.base.BaseProcessor

Hello World Processor example

__init__(provider_def)[source]

Initialize object :param provider_def: provider definition :returns: pygeoapi.process.hello_world.HelloWorldProcessor

__repr__()[source]

Return repr(self).

execute(data)[source]

execute the process :returns: dict of process response

pygeoapi.process.hello_world.PROCESS_METADATA = {'description': 'Hello World process', 'example': {'inputs': [{'id': 'name', 'value': 'hi there', 'type': 'text/plain'}]}, 'id': 'hello-world', 'inputs': [{'id': 'name', 'title': 'name', 'input': {'literalDataDomain': {'dataType': 'string', 'valueDefinition': {'anyValue': True}}}, 'minOccurs': 1, 'maxOccurs': 1}], 'keywords': ['hello world'], 'links': [{'type': 'text/html', 'rel': 'canonical', 'title': 'information', 'href': 'https://example.org/process', 'hreflang': 'en-US'}], 'outputs': [{'id': 'hello-world-response', 'title': 'output hello world', 'output': {'formats': [{'mimeType': 'application/json'}]}}], 'title': 'Hello World process', 'version': '0.1.0'}

Process metadata and description

Provider

Provider module containing the plugins wrapping data sources

Base class

class pygeoapi.provider.base.BaseProvider(provider_def)[source]

Bases: object

generic Provider ABC

__init__(provider_def)[source]

Initialize object

Parameters:provider_def – provider definition
Returns:pygeoapi.providers.base.BaseProvider
__repr__()[source]

Return repr(self).

__weakref__

list of weak references to the object (if defined)

create(new_feature)[source]

Create a new feature

delete(identifier)[source]

Updates an existing feature id with new_feature

Parameters:identifier – feature id
get(identifier)[source]

query the provider by id

Parameters:identifier – feature id
Returns:dict of single GeoJSON feature
get_fields()[source]

Get provider field information (names, types)

Returns:dict of fields
query()[source]

query the provider

Returns:dict of 0..n GeoJSON features
update(identifier, new_feature)[source]

Updates an existing feature id with new_feature

Parameters:
  • identifier – feature id
  • new_feature – new GeoJSON feature dictionary
exception pygeoapi.provider.base.ProviderConnectionError[source]

Bases: Exception

query / backend error

__weakref__

list of weak references to the object (if defined)

exception pygeoapi.provider.base.ProviderQueryError[source]

Bases: Exception

query / backend error

__weakref__

list of weak references to the object (if defined)

exception pygeoapi.provider.base.ProviderVersionError[source]

Bases: Exception

Incorrect provider version

__weakref__

list of weak references to the object (if defined)

CSV provider

class pygeoapi.provider.csv_.CSVProvider(provider_def)[source]

Bases: pygeoapi.provider.base.BaseProvider

CSV provider

_load(startindex=0, limit=10, resulttype='results', identifier=None, bbox=[], time=None, properties=[])[source]

Load CSV data

Parameters:
  • startindex – starting record to return (default 0)
  • limit – number of records to return (default 10)
  • resulttype – return results or hit limit (default results)
  • properties – list of tuples (name, value)
Returns:

dict of GeoJSON FeatureCollection

get(identifier)[source]

query CSV id

Parameters:identifier – feature id
Returns:dict of single GeoJSON feature
query(startindex=0, limit=10, resulttype='results', bbox=[], time=None, properties=[], sortby=[])[source]

CSV query

Parameters:
  • startindex – starting record to return (default 0)
  • limit – number of records to return (default 10)
  • resulttype – return results or hit limit (default results)
  • bbox – bounding box [minx,miny,maxx,maxy]
  • time – temporal (datestamp or extent)
  • properties – list of tuples (name, value)
  • sortby – list of dicts (property, order)
Returns:

dict of GeoJSON FeatureCollection

Elasticsearch provider

class pygeoapi.provider.elasticsearch_.ElasticsearchProvider(provider_def)[source]

Bases: pygeoapi.provider.base.BaseProvider

Elasticsearch Provider

get(identifier)[source]

Get ES document by id

Parameters:identifier – feature id
Returns:dict of single GeoJSON feature
get_fields()[source]
Get provider field information (names, types)
Returns:dict of fields
query(startindex=0, limit=10, resulttype='results', bbox=[], time=None, properties=[], sortby=[])[source]

query Elasticsearch index

Parameters:
  • startindex – starting record to return (default 0)
  • limit – number of records to return (default 10)
  • resulttype – return results or hit limit (default results)
  • bbox – bounding box [minx,miny,maxx,maxy]
  • time – temporal (datestamp or extent)
  • properties – list of tuples (name, value)
  • sortby – list of dicts (property, order)
Returns:

dict of 0..n GeoJSON features

GeoJSON

class pygeoapi.provider.geojson.GeoJSONProvider(provider_def)[source]

Bases: pygeoapi.provider.base.BaseProvider

Provider class backed by local GeoJSON files

This is meant to be simple (no external services, no dependencies, no schema)

at the expense of performance (no indexing, full serialization roundtrip on each request)

Not thread safe, a single server process is assumed

This implementation uses the feature ‘id’ heavily and will override any ‘id’ provided in the original data. The feature ‘properties’ will be preserved.

TODO: * query method should take bbox * instead of methods returning FeatureCollections, we should be yielding Features and aggregating in the view * there are strict id semantics; all features in the input GeoJSON file must be present and be unique strings. Otherwise it will break. * How to raise errors in the provider implementation such that * appropriate HTTP responses will be raised

_load()[source]

Load and validate the source GeoJSON file at self.data

Yes loading from disk, deserializing and validation happens on every request. This is not efficient.

create(new_feature)[source]

Create a new feature

Parameters:new_feature – new GeoJSON feature dictionary
delete(identifier)[source]

Updates an existing feature id with new_feature

Parameters:identifier – feature id
get(identifier)[source]

query the provider by id

Parameters:identifier – feature id
Returns:dict of single GeoJSON feature
query(startindex=0, limit=10, resulttype='results', bbox=[], time=None, properties=[], sortby=[])[source]

query the provider

Parameters:
  • startindex – starting record to return (default 0)
  • limit – number of records to return (default 10)
  • resulttype – return results or hit limit (default results)
  • bbox – bounding box [minx,miny,maxx,maxy]
  • time – temporal (datestamp or extent)
  • properties – list of tuples (name, value)
  • sortby – list of dicts (property, order)
Returns:

FeatureCollection dict of 0..n GeoJSON features

update(identifier, new_feature)[source]

Updates an existing feature id with new_feature

Parameters:
  • identifier – feature id
  • new_feature – new GeoJSON feature dictionary

GeoPackage

class pygeoapi.provider.geopackage.GeoPackageProvider(provider_def)[source]

Bases: pygeoapi.provider.base.BaseProvider

Generic provider for geopackage based on spatialite and geopackage module This module requires install of libsqlite3-mod-spatialite TODO: DELETE, UPDATE, CREATE

_GeoPackageProvider__load()

Private method for loading Geopackage,

Returns:sqlite3.Cursor
_GeoPackageProvider__response_feature_collection()

Assembles GeoJSON output from DB query

Returns:GeoJSON FeaturesCollection
_GeoPackageProvider__response_feature_hits(hits)

Assembles GeoJSON/Feature number e,g: http://localhost:5000/collections/poi/items?resulttype=hits

Returns:GeoJSON FeaturesCollection
_GeoPackageProvider__unload()

Private method for unloading and deleting views in Geopackage, this method is only called when provider is delete at end of query

Returns:None
get(identifier)[source]

Query the provider for a specific feature id e.g: /collections/poi/items/1

Parameters:identifier – feature id
Returns:GeoJSON FeaturesCollection
query(startindex=0, limit=10, resulttype='results', bbox=[], time=None, properties=[], sortby=[])[source]

Query Geopackage for all the content. e,g: http://localhost:5000/collections/poi/items? limit=1&resulttype=results

Parameters:
  • startindex – starting record to return (default 0)
  • limit – number of records to return (default 10)
  • resulttype – return results or hit limit (default results)
  • bbox – bounding box [minx,miny,maxx,maxy]
  • time – temporal (datestamp or extent)
  • properties – list of tuples (name, value)
  • sortby – list of dicts (property, order)
Returns:

GeoJSON FeaturesCollection

OGR

class pygeoapi.provider.ogr.CommonSourceHelper(provider)[source]

Bases: pygeoapi.provider.ogr.SourceHelper

SourceHelper for most common OGR Source types: Shapefile, GeoPackage, SQLite, GeoJSON etc.

close()[source]

OGR Driver-specific handling of closing dataset. If ExecuteSQL has been (successfully) called must close ResultSet explicitly. https://gis.stackexchange.com/questions/114112/explicitly-close-a-ogr-result-object-from-a-call-to-executesql # noqa

disable_paging()[source]

Disable paged access to dataset (OGR Driver-specific)

enable_paging(startindex=-1, limit=-1)[source]

Enable paged access to dataset (OGR Driver-specific) using OGR SQL https://www.gdal.org/ogr_sql.html e.g. SELECT * FROM poly LIMIT 10 OFFSET 30

get_layer()[source]

Gets OGR Layer from opened OGR dataset. When startindex defined 1 or greater will invoke OGR SQL SELECT with LIMIT and OFFSET and return as Layer as ResultSet from ExecuteSQL on dataset. :return: OGR layer object

class pygeoapi.provider.ogr.ESRIJSONHelper(provider)[source]

Bases: pygeoapi.provider.ogr.SourceHelper

disable_paging()[source]

Disable paged access to dataset (OGR Driver-specific)

enable_paging(startindex=-1, limit=-1)[source]

Enable paged access to dataset (OGR Driver-specific)

exception pygeoapi.provider.ogr.InvalidHelperError[source]

Bases: Exception

Invalid helper

class pygeoapi.provider.ogr.OGRProvider(provider_def)[source]

Bases: pygeoapi.provider.base.BaseProvider

OGR Provider. Uses GDAL/OGR Python-bindings to access OGR Vector sources. References: https://pcjericks.github.io/py-gdalogr-cookbook/ https://www.gdal.org/ogr_formats.html (per-driver specifics).

In theory any OGR source type (Driver) could be used, although some Source Types are Driver-specific handling. This is handled in Source Helper classes, instantiated per Source-Type.

The following Source Types have been tested to work: GeoPackage (GPKG), SQLite, GeoJSON, ESRI Shapefile, WFS v2.

_load_source_helper(source_type)[source]

Loads Source Helper by name.

Parameters:type (Source) – Source type name
Returns:Source Helper object
_response_feature_collection(layer, limit)[source]

Assembles output from Layer query as GeoJSON FeatureCollection structure.

Returns:GeoJSON FeatureCollection
_response_feature_hits(layer)[source]

Assembles GeoJSON hits from OGR Feature count e.g: http://localhost:5000/collections/ hotosm_bdi_waterways/items?resulttype=hits

Returns:GeoJSON FeaturesCollection
get(identifier)[source]

Get Feature by id

Parameters:identifier – feature id
Returns:feature collection
get_fields()[source]
Get provider field information (names, types)
Returns:dict of fields
query(startindex=0, limit=10, resulttype='results', bbox=[], time=None, properties=[], sortby=[])[source]

Query OGR source

Parameters:
  • startindex – starting record to return (default 0)
  • limit – number of records to return (default 10)
  • resulttype – return results or hit limit (default results)
  • bbox – bounding box [minx,miny,maxx,maxy]
  • time – temporal (datestamp or extent)
  • properties – list of tuples (name, value)
  • sortby – list of dicts (property, order)
Returns:

dict of 0..n GeoJSON features

class pygeoapi.provider.ogr.SourceHelper(provider)[source]

Bases: object

Helper classes for OGR-specific Source Types (Drivers). For some actions Driver-specific settings or processing is required. This is delegated to the OGR SourceHelper classes.

close()[source]

OGR Driver-specific handling of closing dataset. Default is no specific handling.

disable_paging()[source]

Disable paged access to dataset (OGR Driver-specific)

enable_paging(startindex=-1, limit=-1)[source]

Enable paged access to dataset (OGR Driver-specific)

get_layer()[source]

Default action to get a Layer object from opened OGR Driver. :return:

class pygeoapi.provider.ogr.WFSHelper(provider)[source]

Bases: pygeoapi.provider.ogr.SourceHelper

disable_paging()[source]

Disable paged access to dataset (OGR Driver-specific)

enable_paging(startindex=-1, limit=-1)[source]

Enable paged access to dataset (OGR Driver-specific)

postgresql

class pygeoapi.provider.postgresql.DatabaseConnection(conn_dic, table, context='query')[source]

Bases: object

Database connection class to be used as ‘with’ statement. The class returns a connection object.

class pygeoapi.provider.postgresql.PostgreSQLProvider(provider_def)[source]

Bases: pygeoapi.provider.base.BaseProvider

Generic provider for Postgresql based on psycopg2 using sync approach and server side cursor (using support class DatabaseCursor)

_PostgreSQLProvider__response_feature_collection()

Assembles GeoJSON output from DB query

Returns:GeoJSON FeaturesCollection
_PostgreSQLProvider__response_feature_hits(hits)

Assembles GeoJSON/Feature number e.g: http://localhost:5000/collections/ hotosm_bdi_waterways/items?resulttype=hits

Returns:GeoJSON FeaturesCollection
get(identifier)[source]

Query the provider for a specific feature id e.g: /collections/hotosm_bdi_waterways/items/13990765

Parameters:identifier – feature id
Returns:GeoJSON FeaturesCollection
query(startindex=0, limit=10, resulttype='results', bbox=[], time=None, properties=[], sortby=[])[source]

Query Postgis for all the content. e,g: http://localhost:5000/collections/hotosm_bdi_waterways/items? limit=1&resulttype=results

Parameters:
  • startindex – starting record to return (default 0)
  • limit – number of records to return (default 10)
  • resulttype – return results or hit limit (default results)
  • bbox – bounding box [minx,miny,maxx,maxy]
  • time – temporal (datestamp or extent)
  • properties – list of tuples (name, value)
  • sortby – list of dicts (property, order)
Returns:

GeoJSON FeaturesCollection

sqlite

class pygeoapi.provider.sqlite.SQLiteProvider(provider_def)[source]

Bases: pygeoapi.provider.base.BaseProvider

Generic provider for SQLITE using sqlite3 module. This module requires install of libsqlite3-mod-spatialite TODO: DELETE, UPDATE, CREATE

_SQLiteProvider__load()

Private method for loading spatiallite, get the table structure and dump geometry

Returns:sqlite3.Cursor
_SQLiteProvider__response_feature_collection()

Assembles GeoJSON output from DB query

Returns:GeoJSON FeaturesCollection
_SQLiteProvider__response_feature_hits(hits)

Assembles GeoJSON/Feature number

Returns:GeoJSON FeaturesCollection
get(identifier)[source]

Query the provider for a specific feature id e.g: /collections/countries/items/1

Parameters:identifier – feature id
Returns:GeoJSON FeaturesCollection
query(startindex=0, limit=10, resulttype='results', bbox=[], time=None, properties=[], sortby=[])[source]

Query Sqlite for all the content. e,g: http://localhost:5000/collections/countries/items? limit=1&resulttype=results

Parameters:
  • startindex – starting record to return (default 0)
  • limit – number of records to return (default 10)
  • resulttype – return results or hit limit (default results)
  • bbox – bounding box [minx,miny,maxx,maxy]
  • time – temporal (datestamp or extent)
  • properties – list of tuples (name, value)
  • sortby – list of dicts (property, order)
Returns:

GeoJSON FeaturesCollection