API documentation¶
Top level code documentation. Follow the links in each 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)
-
-
pygeoapi.api.
FORMATS
= ['json', 'html', 'jsonld']¶ Formats allowed for ?f= requests
-
pygeoapi.api.
HEADERS
= {'Content-Type': 'application/json', 'X-Powered-By': 'pygeoapi 0.8.0'}¶ Return headers for requests (e.g:X-Powered-By)
flask_app¶
Flask module providing the route paths to the api
-
pygeoapi.flask_app.
conformance
()[source]¶ OGC open api conformance access point
- Returns
HTTP response
-
pygeoapi.flask_app.
dataset
(collection_id, item_id=None)[source]¶ OGC open api collections/{dataset}/items/{item} 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.
get_collection_queryables
(name=None)[source]¶ OGC open api collections querybles access point
- Parameters
name – identifier of collection name
- Returns
HTTP response
Logging¶
Logging system
OpenAPI¶
-
pygeoapi.openapi.
gen_media_type_object
(media_type, api_type, path)[source]¶ 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)[source]¶ 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
Plugins¶
See also
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', 'FileSystem': 'pygeoapi.provider.filesystem.FileSystemProvider', 'GeoJSON': 'pygeoapi.provider.geojson.GeoJSONProvider', '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
Utils¶
Generic util functions used in the code
-
pygeoapi.util.
dategetter
(date_property, collection)[source]¶ 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.
filter_dict_by_key_value
(dict_, key, value)[source]¶ helper generator function to filter a dict by a dict key
- Parameters
dict –
dict
key – dict key
value – dict key value
- Returns
filtered
dict
helper function to make breadcrumbs from a URL path
- Parameters
urlpath – URL path
- Returns
list of dict objects of labels and links
-
pygeoapi.util.
get_mimetype
(filename)[source]¶ helper function to return MIME type of a given file
- Parameters
filename – filename (with extension)
- Returns
MIME type of given filename
-
pygeoapi.util.
get_path_basename
(urlpath)[source]¶ Helper function to derive file basename
- Parameters
urlpath – URL path
- Returns
string of basename of URL path
-
pygeoapi.util.
get_typed_value
(value)[source]¶ Derive true type from data value
- Parameters
value – value
- Returns
value as a native Python data type
-
pygeoapi.util.
is_url
(urlstring)[source]¶ 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)[source]¶ 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)[source]¶ 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)[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
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
-
__weakref__
¶ list of weak references to the object (if defined)
-
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
-
__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
-
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
-
__weakref__
¶ list of weak references to the object (if defined)
-
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
-
-
exception
pygeoapi.provider.base.
ProviderConnectionError
[source]¶ Bases:
pygeoapi.provider.base.ProviderGenericError
provider connection error
-
exception
pygeoapi.provider.base.
ProviderGenericError
[source]¶ Bases:
Exception
provider generic error
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
exception
pygeoapi.provider.base.
ProviderItemNotFoundError
[source]¶ Bases:
pygeoapi.provider.base.ProviderGenericError
provider query error
-
exception
pygeoapi.provider.base.
ProviderNotFoundError
[source]¶ Bases:
pygeoapi.provider.base.ProviderGenericError
provider not found error
-
exception
pygeoapi.provider.base.
ProviderQueryError
[source]¶ Bases:
pygeoapi.provider.base.ProviderGenericError
provider query error
-
exception
pygeoapi.provider.base.
ProviderVersionError
[source]¶ Bases:
pygeoapi.provider.base.ProviderGenericError
provider incorrect version error
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=[], datetime=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=[], datetime=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]
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)[source]¶ Bases:
pygeoapi.provider.base.BaseProvider
Elasticsearch Provider
-
esdoc2geojson
(doc)[source]¶ generate GeoJSON dict from ES document
- Parameters
doc – dict of ES document
- Returns
GeoJSON dict
-
get
(identifier)[source]¶ Get ES document by id
- Parameters
identifier – feature id
- Returns
dict of single GeoJSON feature
-
mask_prop
(property_name)[source]¶ generate property name based on ES backend setup
- Parameters
property_name – property name
- Returns
masked property name
-
query
(startindex=0, limit=10, resulttype='results', bbox=[], datetime=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]
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)[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=[], datetime=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]
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
-
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
-
enable_paging
(startindex=- 1, limit=- 1)[source]¶ Enable paged access to dataset (OGR Driver-specific) using OGR SQL https://gdal.org/user/ogr_sql_dialect.html e.g. SELECT * FROM poly LIMIT 10 OFFSET 30
-
-
class
pygeoapi.provider.ogr.
ESRIJSONHelper
(provider)[source]¶
-
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://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
-
query
(startindex=0, limit=10, resulttype='results', bbox=[], datetime=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]
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)[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.
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__get_where_clauses
(properties=[], bbox=[])¶ Generarates WHERE conditions to be implemented in query. Private method mainly associated with query method :param properties: list of tuples (name, value) :param bbox: bounding box [minx,miny,maxx,maxy]
- Returns
psycopg2.sql.Composed or psycopg2.sql.SQL
-
_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)[source]¶ Query the provider for a specific feature id e.g: /collections/hotosm_bdi_waterways/items/13990765
- Parameters
identifier – feature id
- Returns
GeoJSON FeaturesCollection
-
get_next
(cursor, identifier)[source]¶ Query next ID given current ID
- Parameters
identifier – feature id
- Returns
feature id
-
get_previous
(cursor, identifier)[source]¶ 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=[])[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]
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)[source]¶ 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__get_where_clauses
(properties=[], bbox=[])¶ Generarates WHERE conditions to be implemented in query. Private method mainly associated with query method.
Method returns part of the SQL query, plus tupple to be used in the sqlite query method
- Parameters
properties – list of tuples (name, value)
bbox – bounding box [minx,miny,maxx,maxy]
- Returns
str, tuple
-
_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)[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=[], datetime=None, properties=[], sortby=[])[source]¶ 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
-