Python API

emissionsapi.autoupdater module

emissionsapi.autoupdater.generate_intervals(start, end, days=5)

Generator for intervals between start and end in days intervals.

Parameters

start (datetime.datetime) – Starting datetime for the intervals.
end (datetime.datetime) – End datetime for the intervals.
days (int, optional) – Days for each interval, defaults to 5

Yield

Start and end date of the next interval.

Return type

tuple

emissionsapi.autoupdater.get_intervals_to_process(session, table, exclude_existing=True)

Get all intervals with associated product files to process. Intervals with existing data will be skipped.

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
table (sqlalchemy.sql.schema.Table) – Table to search for existing data.
ignore_existing (bool, optional) – Exclude existing intervals, defaults to True

Returns

Generator yielding the next interval.

Return type

generator

emissionsapi.autoupdater.main(): Entrypoint for running this as a module or from the binary. Triggers the autoupdater. The autoupdater will download and add all missing product files of the configured products and the configured interval to the database.

emissionsapi.autoupdater.single_file_update(session, product_file, directory, product)

Download a single file, add it to the database and delete the file afterwards.

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
product_file (dict) – Metadata of a single product file as received from sentinal5dl.search.
directory (string) – Directory to download file to.
product (dict) – Type of the processed product. An entry of emissionsapi.db.products.

emissionsapi.config module

Load and handle Emissions API configuration.

emissionsapi.config.config(*args)

Get a specific configuration value or the whole configuration, loading the configuration file if it was not before.

Parameters: key (string) – optional configuration key to return
Returns: dictionary containing the configuration or configuration value

emissionsapi.config.configuration_file()

Find the best match for the configuration file. The configuration file locations taken into consideration are (in this particular order):

./emissionsapi.yml
~/emissionsapi.yml
/etc/emissionsapi.yml

Returns: configuration file name or None

emissionsapi.config.update_configuration(): Update configuration.

emissionsapi.country_shapes module

emissionsapi.db module

Database layer for the Emmission API.

class emissionsapi.db.AlembicVersion(*args: Any, **kwargs: Any): Bases: sqlalchemy.ext.declarative.

class emissionsapi.db.Cache(*args: Any, **kwargs: Any)

Bases: sqlalchemy.ext.declarative.

ORM object for the request cache

classmethod invalidate(session, earliest, latest)

Invalidates/deletes all cached responses in the given interval to ensure these data is generated anew. This is meant to be run when the underlying data for this interval changes, for instance since new data has been imported.

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
earliest (datetime.datetime) – Earliest time of the interval to invalidate
latest (datetime.datetime) – Latest time of the interval to invalidate

class emissionsapi.db.File(*args: Any, **kwargs: Any)

Bases: sqlalchemy.ext.declarative.

ORM object for the nc files.

emissionsapi.db.filter_query(query, tbl, wkt=None, distance=None, begin=None, end=None)

Filter query by time and location.

Parameters

query (sqlalchemy.orm.Query) – SQLAlchemy Query
tbl (sqlalchemy.sql.schema.Table) – Table to get data from
wkt (geoalchemy2.WKTElement, optional) – WKT Element specifying an area in which to search for points, defaults to None.
distance (float, optional) – Distance as defined in PostGIS’ ST_DWithin function.
begin (datetime.datetime, optional) – Get only points after this timestamp, defaults to None
end (datetime.datetime, optional) – Get only points before this timestamp, defaults to None

Returns

SQLAlchemy Query filtered by time and location.

Return type

sqlalchemy.orm.query.Query

emissionsapi.db.get_averages(session, tbl)

Get daily averages of all points.

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
tbl (sqlalchemy.sql.schema.Table) – Table to get data from

Returns

SQLAlchemy Query with tuple of the daily carbon monoxide average, the maximal timestamp the minimal timestamp and the timestamp truncated by day.

Return type

sqlalchemy.orm.query.Query

emissionsapi.db.get_data_range(session, tbl)

Get the range of data currently available from the API.

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
tbl (sqlalchemy.sql.schema.Table) – Table to get data from

Returns

SQLAlchemy Query requesting the minimum and maximum measurement time from all values.

Return type

sqlalchemy.orm.query.Query

emissionsapi.db.get_points(session, tbl)

Get all points.

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
tbl (sqlalchemy.sql.schema.Table) – Table to get data from

Returns

SQLAlchemy Query returning tuples of value, timestamp, longitude, and latitude.

Return type

sqlalchemy.orm.query.Query

emissionsapi.db.get_session()

Get a new session.

Lazy load the database connection and create the tables.

Returns:: sqlalchemy.orm.session.Session – SQLAlchemy Session object

emissionsapi.db.get_statistics(session, tbl, interval_length='day')

Get statistical data like amount, average, min, or max values for a specified time interval. Optionally, time and location filters can be applied.

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
tbl (sqlalchemy.sql.schema.Table) – Table to get data from
interval_length (str) – Length of the time interval for which data is being aggregated as accepted by PostgreSQL’s date_trunc function like day or week.

Returns

SQLAlchemy Query requesting the following statistical values for the specified time interval:

number of considered measurements
average product value
minimum product value
maximum product value
time of the first measurement
time of the last measurement
start of the interval

Return type

sqlalchemy.orm.query.Query

emissionsapi.db.insert_dataset(session, data, tbl)

Batch insert data into the database using PostGIS specific functions.

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
data (pandas.core.frame.DataFrame) – DataFrame containing value, timestamp, longitude and latitude
tbl (sqlalchemy.ext.declarative.api.DeclarativeMeta) – Base class representing the database table for the data

emissionsapi.db.limit_offset_query(query, limit=None, offset=None)

Apply limit and offset to the query.

Parameters

query (sqlalchemy.orm.Query) – SQLAlchemy Query
limit (int, optional) – Limit number of Items returned, defaults to None
offset (int, optional) – Specify the offset of the first hit to return, defaults to None

Returns

SQLAlchemy Query with limit and offset applied.

Return type

sqlalchemy.orm.query.Query

emissionsapi.db.with_session(f)

Wrapper for f to make a SQLAlchemy session present within the function

Parameters: f (Function) – Function to call
Raises: e – Possible exception of f
Returns: Result of f

emissionsapi.preprocess module

Preprocess the locally stored data and store them in the database.

emissionsapi.preprocess.list_ncfiles(session, storage)

list all nc files in storage.

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
storage (str) – Path to the directory containing the *.nc files

Returns

Set of all unprocessed files

Return type

set

emissionsapi.preprocess.main(): Entrypoint for running this as a module or from the binary. Triggers the preprocessing of the data.

emissionsapi.preprocess.preprocess_file(ncfile, tbl, product)

Preprocess a single file and write it to the database

Parameters

ncfile (str) – path to the ncfile to preprocess
tbl (sqlalchemy.sql.schema.Table) – Table to to write data to
product (str) – The name of the product to load from the files

emissionsapi.preprocess.write_to_database(session, data, filepath, tbl)

Write data to the PostGIS database

Parameters

session (sqlalchemy.orm.session.Session) – SQLAlchemy Session
tbl (sqlalchemy.sql.schema.Table) – Table to to write data to
data (pandas.core.frame.DataFrame) – Data to add to the database
filepath (str) – Path to the file being imported
tbl – Table to to write data to

emissionsapi.utils module

exception emissionsapi.utils.RESTParamError

Bases: ValueError

User-specific exception, used in polygon_to_wkt().

emissionsapi.utils.bounding_box_to_wkt(lon1, lat1, lon2, lat2): Convert a bounding box specified by its top-left and bottom-right coordinates to a wkt string defining a polygon.

emissionsapi.utils.polygon_to_wkt(polygon)

Converts a list of points to a WKT string defining a polygon.

Parameters: polygon (list) – List of values with every pair of values representing a consecutive vertex of the polygon.
Returns: WKT defining the polygon.
Return type: str

emissionsapi.web module

Module contents

Emissions API

Emissions API’s mission is to provide easy access to European Space Agency’s Sentinel-5P satellite data without the need of being an expert in satellite data analysis and without having to process terabytes of data.

url: https://emissions-api.org
license: MIT