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)

API object

__init__(config)

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)

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_collection_items(headers, args, dataset, pathinfo=None)

Queries feature collection

Parameters:

• headers – dict of HTTP headers
• args – dict of HTTP request parameters
• dataset – dataset name
• pathinfo – path location

Returns:

tuple of headers, status code, content

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

Formats allowed for ?f= requests

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

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

pygeoapi.api.check_format(args, headers)

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)

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

Parameters:func – decorated function Returns:func

flask_app

Flask module providing the route paths to the api

pygeoapi.flask_app.conformance()

OGC open api conformance access point

Returns:HTTP response

pygeoapi.flask_app.dataset(feature_collection, feature=None)

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

Returns:HTTP response

pygeoapi.flask_app.describe_collections(name=None)

OGC open api collections access point

Parameters:name – identifier of collection name Returns:HTTP response

pygeoapi.flask_app.describe_processes(name=None)

OGC open api processes access point (experimental)

Parameters:name – identifier of process to describe Returns:HTTP response

pygeoapi.flask_app.execute_process(name=None)

OGC open api jobs from processes access point (experimental)

Parameters:name – identifier of process to execute Returns:HTTP response

pygeoapi.flask_app.openapi()

OpenAPI access point

Returns:HTTP response

pygeoapi.flask_app.root()

HTTP root content of pygeoapi. Intro page access point

Returns:HTTP response

Logging

Logging system

pygeoapi.log.setup_logger(logging_config)

Setup configuration

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

OpenAPI

pygeoapi.openapi.gen_media_type_object(media_type, api_type, path)

Generates an OpenAPI Media Type Object

Parameters:

• media_type – MIME type
• api_type – OGC API type
• path – local path of OGC API parameter or schema definition

Returns:

dict of media type object

pygeoapi.openapi.gen_response_object(description, media_type, api_type, path)

Generates an OpenAPI Response Object

Parameters:

• description – text description of response
• media_type – MIME type
• api_type – OGC API type

Returns:

dict of response object

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

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)

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

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', 'MongoDB': 'pygeoapi.provider.mongo.MongoProvider', 'OGR': 'pygeoapi.provider.ogr.OGRProvider', 'PostgreSQL': 'pygeoapi.provider.postgresql.PostgreSQLProvider', 'SQLiteGPKG': 'pygeoapi.provider.sqlite.SQLiteGPKGProvider'}}

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

pygeoapi.plugin.load_plugin(plugin_type, plugin_def)

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.dategetter(date_property, collection)

Attempts to obtains a date value from a collection.

Parameters:

• date_property – property representing the date
• collection – dictionary to check within

Returns:

str (ISO8601) representing the date. (‘..’ if null or “now”, allowing for an open interval).

pygeoapi.util.get_typed_value(value)

Derive true type from data value

Parameters:value – value Returns:value as a native Python data type

pygeoapi.util.is_url(urlstring)

Validation function that determines whether a candidate URL should be considered a URI. No remote resource is obtained; this does not check the existence of any remote resource. :param urlstring: str to be evaluated as candidate URL. :returns: bool of whether the URL looks like a URL.

pygeoapi.util.json_serial(obj)

helper function to convert to JSON non-default types (source: https://stackoverflow.com/a/22238613) :param obj: object to be evaluated :returns: JSON non-default type to str

pygeoapi.util.render_j2_template(config, template, data)

render Jinja2 template

Parameters:

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

Returns:

string of rendered template

pygeoapi.util.str2bool(value)

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.to_json(dict_)

Serialize dict to json

Parameters:dict – dict of JSON representation Returns:JSON string representation

pygeoapi.util.yaml_load(fh)

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)

Bases: object

generic Formatter ABC

__init__(formatter_def)

Initialize object

Parameters:formatter_def – formatter definition Returns:pygeoapi.providers.base.BaseFormatter

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

write(options={}, data=None)

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)

Bases: pygeoapi.formatter.base.BaseFormatter

CSV formatter

__init__(formatter_def)

Initialize object

Parameters:formatter_def – formatter definition Returns:pygeoapi.formatter.csv_.CSVFormatter

__repr__()

Return repr(self).

write(options={}, data=None)

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)

Bases: object

generic Processor ABC. Processes are inherited from this class

__init__(processor_def, process_metadata)

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

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

execute()

execute the process :returns: dict of process response

exception pygeoapi.process.base.ProcessorExecuteError

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)

Bases: pygeoapi.process.base.BaseProcessor

Hello World Processor example

__init__(provider_def)

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

__repr__()

Return repr(self).

execute(data)

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)

Bases: object

generic Provider ABC

__init__(provider_def)

Initialize object

Parameters:provider_def – provider definition Returns:pygeoapi.providers.base.BaseProvider

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

create(new_feature)

Create a new feature

delete(identifier)

Updates an existing feature id with new_feature

Parameters:identifier – feature id

get(identifier)

query the provider by id

Parameters:identifier – feature id Returns:dict of single GeoJSON feature

get_fields()

Get provider field information (names, types)

Returns:dict of fields

query()

query the provider

Returns:dict of 0..n GeoJSON features

update(identifier, new_feature)

Updates an existing feature id with new_feature

Parameters:

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

exception pygeoapi.provider.base.ProviderConnectionError

Bases: Exception

query / backend error

__weakref__

list of weak references to the object (if defined)

exception pygeoapi.provider.base.ProviderQueryError

Bases: Exception

query / backend error

__weakref__

list of weak references to the object (if defined)

exception pygeoapi.provider.base.ProviderVersionError

Bases: Exception

Incorrect provider version

__weakref__

list of weak references to the object (if defined)

CSV provider

class pygeoapi.provider.csv_.CSVProvider(provider_def)

Bases: pygeoapi.provider.base.BaseProvider

CSV provider

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

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)

query CSV id

Parameters:identifier – feature id Returns:dict of single GeoJSON feature

query(startindex=0, limit=10, resulttype='results', bbox=[], datetime=None, properties=[], sortby=[])

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]
• datetime – 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)

Bases: pygeoapi.provider.base.BaseProvider

Elasticsearch Provider

get(identifier)

Get ES document by id

Parameters:identifier – feature id Returns:dict of single GeoJSON feature

get_fields()

Get provider field information (names, types)

Returns:dict of fields

query(startindex=0, limit=10, resulttype='results', bbox=[], datetime=None, properties=[], sortby=[])

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]
• datetime – 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)

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()

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)

Create a new feature

Parameters:new_feature – new GeoJSON feature dictionary

delete(identifier)

Updates an existing feature id with new_feature

Parameters:identifier – feature id

get(identifier)

query the provider by id

Parameters:identifier – feature id Returns:dict of single GeoJSON feature

query(startindex=0, limit=10, resulttype='results', bbox=[], datetime=None, properties=[], sortby=[])

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]
• datetime – 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)

Updates an existing feature id with new_feature

Parameters:

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

OGR

class pygeoapi.provider.ogr.CommonSourceHelper(provider)

Bases: pygeoapi.provider.ogr.SourceHelper

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

close()

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()

Disable paged access to dataset (OGR Driver-specific)

enable_paging(startindex=-1, limit=-1)

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()

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)

Bases: pygeoapi.provider.ogr.SourceHelper

disable_paging()

Disable paged access to dataset (OGR Driver-specific)

enable_paging(startindex=-1, limit=-1)

Enable paged access to dataset (OGR Driver-specific)

exception pygeoapi.provider.ogr.InvalidHelperError

Bases: Exception

Invalid helper

class pygeoapi.provider.ogr.OGRProvider(provider_def)

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)

Loads Source Helper by name.

Parameters:type (Source) – Source type name Returns:Source Helper object

_response_feature_collection(layer, limit)

Assembles output from Layer query as GeoJSON FeatureCollection structure.

Returns:GeoJSON FeatureCollection

_response_feature_hits(layer)

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

Returns:GeoJSON FeaturesCollection

get(identifier)

Get Feature by id

Parameters:identifier – feature id Returns:feature collection

get_fields()

Get provider field information (names, types)

Returns:dict of fields

query(startindex=0, limit=10, resulttype='results', bbox=[], datetime=None, properties=[], sortby=[])

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]
• datetime – 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)

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()

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

disable_paging()

Disable paged access to dataset (OGR Driver-specific)

enable_paging(startindex=-1, limit=-1)

Enable paged access to dataset (OGR Driver-specific)

get_layer()

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

class pygeoapi.provider.ogr.WFSHelper(provider)

Bases: pygeoapi.provider.ogr.SourceHelper

disable_paging()

Disable paged access to dataset (OGR Driver-specific)

enable_paging(startindex=-1, limit=-1)

Enable paged access to dataset (OGR Driver-specific)

postgresql

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

Bases: object

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

class pygeoapi.provider.postgresql.PostgreSQLProvider(provider_def)

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(row_data)

Assembles GeoJSON output from DB query

Parameters:row_data – DB row result Returns:dict of GeoJSON Feature

_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)

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

Parameters:identifier – feature id Returns:GeoJSON FeaturesCollection

get_fields()

Get fields from PostgreSQL table (columns are field)

Returns:dict of fields

get_next(cursor, identifier)

Query next ID given current ID

Parameters:identifier – feature id Returns:feature id

get_previous(cursor, identifier)

Query previous ID given current ID

Parameters:identifier – feature id Returns:feature id

query(startindex=0, limit=10, resulttype='results', bbox=[], datetime=None, properties=[], sortby=[])

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]
• datetime – temporal (datestamp or extent)
• properties – list of tuples (name, value)
• sortby – list of dicts (property, order)

Returns:

GeoJSON FeaturesCollection

sqlite/geopackage

class pygeoapi.provider.sqlite.SQLiteGPKGProvider(provider_def)

Bases: pygeoapi.provider.base.BaseProvider

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

_SQLiteGPKGProvider__load()

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

Returns:sqlite3.Cursor

_SQLiteGPKGProvider__response_feature(row_data)

Assembles GeoJSON output from DB query

Parameters:row_data – DB row result Returns:dict of GeoJSON Feature

_SQLiteGPKGProvider__response_feature_hits(hits)

Assembles GeoJSON/Feature number

Returns:GeoJSON FeaturesCollection

get(identifier)

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

Parameters:identifier – feature id Returns:GeoJSON FeaturesCollection

get_fields()

Get fields from sqlite table (columns are field)

Returns:dict of fields

query(startindex=0, limit=10, resulttype='results', bbox=[], datetime=None, properties=[], sortby=[])

Query SQLite/GPKG for all the content. e,g: http://localhost:5000/collections/countries/items? limit=5&startindex=2&resulttype=results&continent=Europe&admin=Albania&bbox=29.3373,-3.4099,29.3761,-3.3924 http://localhost:5000/collections/countries/items?continent=Africa&bbox=29.3373,-3.4099,29.3761,-3.3924

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]
• datetime – temporal (datestamp or extent)
• properties – list of tuples (name, value)
• sortby – list of dicts (property, order)

Returns:

GeoJSON FeaturesCollection