Usage¶
Basic Usage¶
To use this SAFPIS REST API wrapper library:
from safpis.safpis import Safpis
from tabulate import tabulate
# First ensure you have your SAFPIS Data Publisher Token defined
# in the SAFPIS_SUBSCRIBER_TOKEN environmental variable.
#
# To be secure, it is best to store your SAFPIS Data Publisher
# Token in a file. We provide a convienient way to load the
# token from an ini-style config file using something like:
Safpis.load_token(
ini = "secrets.cfg",
section = "TEST",
key = "SAFPIS_SUBSCRIBER_TOKEN"
)
safpis = Safpis()
# Get list of fuel types
#####
print(tabulate(safpis._fuels(), headers="keys", tablefmt="pretty"))
# Get fuel by name or id
#####
fuel = safpis.fuel_by_name("Unleaded")
fuel.FuelId
fuel = safpis.fuel_by_id(2)
fuel.Name
# Get list of brands
#####
print(tabulate(safpis._brands(), headers="keys", tablefmt="pretty"))
# Get brand by name or id
#####
brand = safpis.brand_by_name("Caltex")
brand.BrandId
brand = safpis.brand_by_id(2)
brand.Name
# Get the list of fuel stations
#####
print(tabulate(safpis._fuel_stations(), headers="keys", tablefmt="pretty"))
# Get fuel stations sorted by distance to a particular location
#####
latitude = -35.073360
longitude = 138.570401
# TODO: this function should allow a list of sites to be provided
# to it and also return the associated distances
fuel_stations = safpis.closest_fuel_stations(
latitude,
longitude,
)
print(tabulate(fuel_stations, headers="keys", tablefmt="pretty"))
# Get the distance to the closest fuel station
#####
fuel_stations[0].distance(latitude, longitude)
# Get the ID's of the closest 5 fuel stations
#####
[fuel_station.S for fuel_station in fuel_stations[0:5]]
# Get fuel stations for a particular brand
#####
fuel_stations = safpis.fuel_stations_by_brand_name("EG Ampol")
print(tabulate(fuel_stations, headers="keys", tablefmt="pretty"))
# Get fuel stations for a particular brand within a certain
# distance
#####
latitude = -35.073360
longitude = 138.570401
brand_name = "On the Run"
max_dist_km = 10
fuel_stations = sorted(
filter(
lambda fuel_station: fuel_station.distance(latitude, longitude)
<= max_dist_km,
safpis.fuel_stations_by_brand_name(brand_name),
),
key=lambda fuel_station: fuel_station.distance(latitude, longitude),
)
print(tabulate(fuel_stations, headers="keys", tablefmt="pretty"))
Working with the REST API¶
To work more directly with the SAFPIS REST API, you can just import and use safpis.api. It provided little more than a wrapper around the API calls, with convienient default request parameters, appropriate caching of the requests and returning of the JSON response:
from safpis.api import SafpisAPI
from safpis.safpis import Safpis
# Load the token from a ini-style config file
Safpis.load_token(
ini = "secrets.cfg",
section = "TEST",
key = "SAFPIS_SUBSCRIBER_TOKEN"
)
api = SafpisAPI()
# The GetCountryBrands endpoint
brands = api.GetCountryBrands()
# The GetCountryGeographicRegions endpoint
regions = api.GetCountryGeographicRegions()
# The GetCountryFuelTypes endpoint
fuel_types = api.GetCountryFuelTypes()
# The GetFullSiteDetails endpoint
fuel_stations = api.GetFullSiteDetails()
# The GetSitesPrices endpoint
prices = api.GetSitesPrices()
Home Assistant Rest Sensor¶
You can generate a rest sensor stub for a tracking the price of fuel at a fuel station of your choice:
# Generate a Home Assistant rest sensor for a particular
# type of fuel from a particular fuel station
#####
def ha_fuel_sensor(fuel_station_id, fuel_id):
site_name = safpis.fuel_station_by_id(fuel_station_id).N
fuel_name = safpis.fuel_by_id(fuel_id).Name
print(f' - name: "{site_name} - {fuel_name}"')
print(f' value_template: "{{ ((value_json.SitePrices|selectattr(\'SiteId\',\'==\',{fuel_station_id})|selectattr(\'FuelId\', \'==\', {fuel_id})|first).Price / 1000) | round(3) }}"')
print(f' unit_of_measurement: AUD')
print(f' state_class: measurement')
# Using the above info, find the ID of a fuel station and fuel
# type for which you want a sensor
#####
fuel_station_id = 61501319
fuel_id = 2
# Double-check the names
safpis.fuel_station_by_id(fuel_station_id).N
safpis.fuel_by_id(fuel_id).FuelId
# Generate the rest sensor text
#####
ha_fuel_sensor(fuel_station_id, fuel_id)
#ha_fuel_sensor(site_name = "EG Ampol Eden Hills", fuel_name = "Unleaded")