=====
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")