Stations API 3.0 usage examples¶
Meteostations¶
Managing meteostations is easy!
Just get a reference to the stationsapi30..stations_manager.StationsManager
object that proxies the OWM Stations API, and then work on it
You can issue CRUD (Create Read Update Delete) actions on the StationsManager
and data is passed in/out in the form of stationsapi30.stations.Station
objects
Here are some examples:
import pyowm
owm = pyowm.OWM('your-API-key')
mgr = owm.stations_manager() # Obtain the Stations API client
# Create a new station
station = mgr.create_station("SF_TEST001", "San Francisco Test Station",
37.76, -122.43, 150)
# Get all your stations
all_stations = mgr.get_stations()
# Get a station named by id
id = '583436dd9643a9000196b8d6'
retrieved_station = mgr.get_station(id)
# Modify a station by editing its "local" proxy object
retrieved_station.name = 'A different name'
mgr.modify_station(retrieved_station)
# Delete a station and all its related measurements
mgr.delete_station(retrieved_station)
Measurements¶
Each meteostation tracks datapoints, each one represented by an object.
Datapoints that you submit to the OWM Stations API (also called “raw
measurements”) are of type: stationsapi30.measurement.Measurement
, while
datapoints that you query against the API come in the form of:
stationsapi30.measurement.AggregatedMeasurement
objects.
Each stationsapi30.measurement.Measurement
contains a reference to the
Station
it belongs to:
measurement.station_id
Create such objects with the class constructor or using the
stationsapi30.measurement.Measurement.from_dict()
utility method.
Once you have a raw measurement or a list of raw measurements (even belonging
to mixed stations), you can submit them to the OWM Stations API via
the StationsManager
proxy:
# Send a new raw measurement for a station
mgr.send_measurement(raw_measurement_obj)
# Send a list of new raw measurements, belonging to multiple stations
mgr.send_measurements(list_of_raw_measurement_objs)
Reading measurements from the OWM Stations API can be easily done using the
StationsManager
as well. As sad, they come in the form of
stationsapi30.measurement.AggregatedMeasurement
instances. Each of such
objects represents an aggregation of measurements for the station that you
specified, with an aggregation time granularity of day, hour or minute -
you tell what. You can query aggregated measurements in any time window.
So when querying for measurements, you need to specify:
- the reference station ID
- the aggregation granularity (as sai, among:
d
,h
andm
) - the time window (start-end Unix timestamps)
- how many results you want
Example:
# Read aggregated measurements (on day, hour or minute) for a station in a given
# time interval
aggr_msmts = mgr.get_measurements(station_id, 'h', 1505424648, 1505425648, limit=5)
Buffers¶
As usually a meteostation tracks a lot of datapoints over time and it is expensive
(eg. in terms of battery and bandwidth usage) to submit them one by one to the
OWM Stations API, a good abstraction tool to work with with measurements is
stationsapi30.buffer.Buffer
objects.
A buffer is basically a “box” that collects multiple measurements for a station. You can use the buffer to store measurements over time and to send all of the measurements to the API at once.
Examples:
from pyowm.stationsapi30.buffer import Buffer
# Create a buffer for a station...
buf = Buffer(station_id)
# ...and append measurement objects to it
buf.append(msmt_1)
buf.append(msmt_2)
buf.append(msmt_3)
# ... or read data from other formats
# -- a dict
# (as you would pass to Measurement.from_dict method)
buf.append_from_dict(msmt_dict)
# -- a JSON string
# that string must be parsable as a dict that you can feed to
# Measurement.from_dict method
with open('my-msmts.json') as j:
buf.append_from_json(j.read())
# buffers are nice objects
# -- they are iterable
print(len(buf))
for measurement in buf:
print(measurement)
# -- they can be joined
new_buf = buf + another_buffer
# -- they can be emptied
buf.empty()
# -- you can order measurements in a buffer by their creation time
buf.sort_chronologically()
buf.sort_reverse_chronologically()
# Send measurements stored in a buffer to the API using the StationManager object
mgr.send_buffer(buf)
You can load/save measurements into/from Buffers from/tom any persistence backend:
- Saving: persist data to the filesystem or to custom data persistence backends that you can provide (eg. databases)
- Loading: You can also pre-load a buffer with (or append to it) measurements stored on the file system or read from custom data persistence backends
The default persistence backend is: stationsapi30.persistence_backend.JSONPersistenceBackend
and allows to read/write buffer data from/to JSON files
As said, you can use your own custom data backends: they must be
subclasses of stationsapi30.persistence_backend.PersistenceBackend
Examples:
from pyowm.stationsapi30 import persistence_backend
# instantiate the default JSON-based backend: you need to provide the ID of the
# stations related to measurements...
json_be = persistence_backend.JSONPersistenceBackend('/home/myfile.json', station_id)
# ... and use it to load a buffer
buf = json_be.load_to_buffer()
# ... and to save buffers
json_be.persist_buffer(buf)
# You can use your own persistence backends
my_custom_be = MyCustomPersistenceBackend()
buf = my_custom_be.load_to_buffer()
my_custom_be.persist_buffer(buf)