smart Module

Examples

Here is an example showing how to benchmark a sea_longterm lane:

from pypply.smart import Smart

token_client = "01hp1***.69aa***"

# Create a Smart object with the desired API environment
smart = Smart(access_token=token_client, env='sandbox')

# Prepare a benchmark payload
payload = {
    "pickup": {
        "latitude": 49.475,
        "longitude": 0.1333328
    },
    "delivery": {
        "latitude": 27.714281,
        "longitude": 106.917885
    },
    "shipment": {
        "container": {
            "unit": "40gp",
            "value": 1
        },
        "hazardous": False
    },
    "schedule": {"etd": "2024-10-25"},
    "pricing": {
        "thc": {
            "origin": True,
            "destination": True
        },
        "service_type": "dtd"
    }
}

# Retrieve benchmark data with optional filters (e.g., rate ranges, emission types)
benchmark_result = smart.benchmark(
    mode='sea_longterm',
    payload=payload,
    emission_types=['co2', 'so2'],
    rate_ranges=['low_high']
)

print(f"Benchmark result: {benchmark_result}")

Here is an example to retrieve all UFIs corresponding to road_emea mode and spot market, and to retrieve historical data for the first one:

from pypply.smart import Smart

token_client = "01hp1***.69aa***"

# Create a Smart object
smart = Smart(access_token=token_client, env='sandbox')

# Retrieve a list of UFIs (e.g., filtering by mode and market)
ufi_list = smart.ufi_list(mode='road_emea', market='spot', lang='en')
print(f"Available UFIs: {ufi_list}")

# Retrieve historical data for a specific UFI code
ufi_code = list(ufi_list.keys())[0]
ufi_historical = smart.ufi_historical(code=ufi_code)
print(f"UFI historical data: {ufi_historical}")

Doc

class pypply.smart.Smart(access_token, env='prod', timeout=5, sleep_time=0.2, retries=0)

Bases: API

Creates a Smart object to use Upply benchmark and UFI products.

Smart.__init__(self, access_token: str, env: str = 'prod', timeout: int = 5, sleep_time: float = 0.2, retries: int = 0)

Initializes a Smart object with authentication and request settings.

• Parameters:
  • access_token (str) – Authentication token required to access the API.
  • env (str) – API environment. Allowed values: prod, sandbox.
  • timeout (int) – Maximum time (in seconds) to wait for a response.
  • sleep_time (float) – Delay (in seconds) between retry attempts.
  • retries (int) – Number of retry attempts in case of a failed request.

Smart.benchmark(self, mode: str, payload: Union[dict[str, Any], list[dict[str, Any]]], historical: bool = False, **kwargs) -> dict[str, dict]

Retrieves lane benchmark.

• Parameters:
  • mode (str) – Transport mode. Allowed values: air, road_emea, road_na, sea_longterm.
  • payload (Union[dict[str, Any], list[dict[str, Any]]]) – Benchmark payload.
  • historical (bool) – Benchmark on multiple dates or not.
• Other Parameters:
  • emission_types (list) – Filter by emission type. Allowed values: co2, nmhc, nox, pm, primaryEnergy, so2.
  • rate_ranges (list) – Filter by rate range. Allowed values: low_high, min_max, no_range.
• Returns: dict[str, dict] – Benchmark result.

Smart.price(self, mode: str, payload: dict[str, typing.Any], **kwargs) -> dict[str, typing.Union[str, dict]]

Retrieves lane prices.

• Parameters:
  • mode (str) – Transport mode. Allowed values: air, road_emea, road_na, sea_longterm.
  • payload (dict[str, Any]) – Benchmark payload.
• Other Parameters: rate_ranges (list) – Filter by rate range. Allowed values: low_high, min_max, no_range.
• Returns: dict[str, Union[str, dict]] – Benchmark results (only rates, not confidence nor emissions).

Smart.confidence(self, mode: str, payload: dict[str, typing.Any]) -> str

Retrieves lane confidence index.

• Parameters:
  • mode (str) – Transport mode. Allowed values: air, road_emea, road_na, sea_longterm.
  • payload (dict[str, Any]) – Benchmark payload.
• Returns: str – Confidence index.

Smart.emissions(self, mode: str, payload: dict[str, typing.Any], **kwargs) -> dict[str, dict]

Retrieves lane emissions.

• Parameters:
  • mode (str) – Transport mode. Allowed values: air, road_emea, road_na, sea_longterm.
  • payload (dict[str, Any]) – Benchmark payload.
• Other Parameters: emission_types (list) – Filter by emission type. Allowed values: co2, nmhc, nox, pm, primaryEnergy, so2.
• Returns: dict[str, dict] – Benchmark results (only emissions, not rates nor confidence).

Smart.benchmark_historical(self, mode: str, payload: dict[str, typing.Any], date_start: str = '2017-01-01', date_end: str = None, lookback_months: int = None, **kwargs) -> dict[str, typing.Union[str, dict]]

Retrieves the benchmark historical.

• Parameters:
  • mode (str) – Transport mode. Allowed values: air, road_emea, road_na, sea_longterm.
  • payload (dict[str, Any]) – Benchmark payload.
  • date_start (str) – Start date of the historical.
  • date_end (str) – End date of the historical.
  • lookback_months (int) – Number of months of historical to compute. If filled, replaces date_start.
• Other Parameters:
  • emission_types (list) – Filter by emission type. Allowed values: co2, nmhc, nox, pm, primaryEnergy, so2.
  • rate_ranges (list) – Filter by rate range. Allowed values: low_high, min_max, no_range.
• Returns: dict[str, Union[str, dict]] – Benchmarks results.

Smart.price_historical(self, mode: str, payload: dict[str, typing.Any], date_start: str = '2017-01-01', date_end: str = None, lookback_months: int = None, **kwargs) -> dict[str, dict]

Retrieves the benchmark historical (only rates).

• Parameters:
  • mode (str) – Transport mode. Allowed values: air, road_emea, road_na, sea_longterm.
  • payload (dict[str, Any]) – Benchmark payload.
  • date_start (str) – Start date of the historical.
  • date_end (str) – End date of the historical.
  • lookback_months (int) – Number of months of historical to compute. If filled, replaces date_start.
• Other Parameters: rate_ranges (list) – Filter by rate range. Allowed values: low_high, min_max, no_range.
• Returns: dict[str, dict] – Benchmarks results (only rates).

Smart.ufi_iter(self, mode: str = None, market: str = None, name: str = '', lang: str = 'fr') -> Iterator[tuple[str, str]]

Streams UFIs, filtered by mode, market and name.

• Parameters:
  • mode (str) – Transport mode. Allowed values: air, road_emea, road_na, sea_longterm.
  • market (str) – Market type. Allowed values: spot, contract, full.
  • name (str) – Name of the UFI to look for.
  • lang (str) – UFI’s name language. Allowed values: fr, en.
• Yields: tuple[str, str] – UFI code and name.

Smart.ufi_list(self, mode: str = None, market: str = None, name: str = '', lang: str = 'fr') -> dict[str, str]

Retrieves list of UFIs, filtered by mode, market and name. Uses the lazy iterator to build the dictionary.

• Parameters:
  • mode (str) – Transport mode. Allowed values: air, road_emea, road_na, sea_longterm.
  • market (str) – Market type. Allowed values: spot, contract, full.
  • name (str) – Name of the UFI to look for.
  • lang (str) – UFI’s name language. Allowed values: fr, en.
• Returns: dict[str, str] – UFIs code and name.

Smart.ufi_historical(self, code: str, date_start: str = '2017-01-01', date_end: str = None, lookback_months: int = None, date_baseline: str = '2017-01-01') -> dict[str, typing.Union[str, dict]]

Retrieves the UFI historical.

• Parameters:
  • code (str) – UFI code.
  • date_start (str) – Start date of the historical.
  • date_end (str) – End date of the historical.
  • lookback_months (int) – Number of months of historical to compute. If filled, replaces date_start.
  • date_baseline (str) – Baseline date to compute base 100 rates.
• Returns: dict[str, Union[str, dict]] – UFI historical rates.

Smart.ufi_forecast(self, code: str, nb_weeks: int = 6, date_baseline: str = '2017-01-01') -> dict[str, typing.Union[str, dict]]

Retrieves the UFI short-term forecast.

• Parameters:
  • code (str) – UFI code.
  • nb_weeks (int) – Number of weeks to forecast.
  • date_baseline (str) – Baseline date to compute base 100 rates.
• Returns: dict[str, Union[str, dict]] – UFI short-term forecast rates.

Smart.ufi_historical_and_forecast(self, code: str, date_start: str = '2017-01-01', date_end: str = None, lookback_months: int = None, nb_weeks_forecast: int = 6, date_baseline: str = '2017-01-01') -> dict[str, dict]

Retrieves the UFI historical and forecast rates.

Returns forecast rates only if date_end is not filled (and nb_weeks_forecast not null) or if date_end >= first forecast rate date.

• Parameters:
  • code (str) – UFI code.
  • date_start (str) – Start date of the historical.
  • date_end (str) – End date of the historical.
  • lookback_months (int) – Number of months of historical to compute. If filled, replaces date_start.
  • nb_weeks_forecast (int) – Number of weeks to forecast.
  • date_baseline (str) – Baseline date to compute base 100 rates.
• Returns: dict[str, dict] – UFI historical and forecast rates.

Smart.ufi_historical_and_forecast_multiple(self, mode: str = None, market: str = None, name: str = '', date_start: str = '2017-01-01', date_end: str = None, lookback_months: int = None, nb_weeks_forecast: int = 6, date_baseline: str = '2017-01-01') -> dict[str, dict]

Retrieves the UFI historical and forecast rates for multiple UFI codes.

Retrieves UFI codes from ufi_list() and retrieves historical / forecast rates for all these UFI codes with ufi_historical_and_forecast(). Returns an empty result if no UFI corresponds to the search.

• Parameters:
  • mode (str) – Transport mode. Allowed values: air, road_emea, road_na, sea_longterm.
  • market (str) – Market type. Allowed values: spot, contract, full.
  • name (str) – Name of the UFI to look for.
  • date_start (str) – Start date of the historical.
  • date_end (str) – End date of the historical.
  • lookback_months (int) – Number of months of historical to compute. If filled, replaces date_start.
  • nb_weeks_forecast (int) – Number of weeks to forecast.
  • date_baseline (str) – Baseline date to compute base 100 rates.
• Returns: dict[str, dict] – UFI historical and forecast rates for all UFI corresponding to UFI search.