# pypply
***pypply* makes it easier to use Upply API by providing a simple, well-structured Python interface for retrieving benchmark rates, UFI data, and geographic information.
With quick and straightforward integration — just like the Upply API — you can get up and running in minutes.
It handles API connections, payload processing, and error management so you can focus on building your application.**
## Table of Contents
- [Features](#features)
- [Global](#global)
- [Products](#products)
- [Installation](#installation)
- [Authentication](#authentication)
- [Usage](#usage)
- [Geography Feature Usage](#geography-feature-usage)
- [Benchmark Features Usage](#benchmark-features-usage)
- [UFI Features Usage](#ufi-features-usage)
- [License](#license)
## Features
### Global
- **Environments**: Easily switch between different API environments. Use the sandbox environment to develop and test your code without running out of credit, and switch to production when you need real Upply data.
- **Payload Processing**: Automatically merge and complete client-provided payloads with default values. This helps reduce code and ensures consistency in your API requests.
- **Validation**: Validate payload structure and input parameters using Pydantic models. This ensures that data sent to the API meets expected formats and types.
- **Error Handling**: Robust error handling with meaningful error messages and logging. This makes debugging easier and ensures that issues are reported clearly to the user.
### Products
#### Geography
- **Geocoding**: Convert a location query (such as a city, airport, or seaport) into its corresponding latitude and longitude.
- **Seamless Integration**: Integrates with benchmark payload processing so that users do not have to supply coordinates manually.
#### Benchmark
- **Benchmark Rates**: Easily retrieve lane benchmark rates for various transport modes (air, road_emea, road_na, sea_longterm) along with their associated rates.
- **Confidence Index**: Obtain a confidence index indicating the reliability of the benchmark result.
- **Emissions**: Retrieve emissions data (e.g., CO₂, SO₂, NOx, etc.) as part of the benchmark response.
- **Default Payload Support**: Use built-in default payloads so that you don't have to specify every parameter manually.
- **Geolocation Integration**: Benchmark requests can automatically fetch latitude and longitude data, eliminating the need for users to provide coordinates explicitly.
#### UFI
- **List Available UFIs**: Easily list and filter available UFIs by transport mode, market, and name.
- **Historical Data**: Retrieve historical UFI data for specified periods with flexible filtering options such as date ranges and number of months.
- **Forecast Data**: Retrieve short-term forecast rates with a configurable number of forecast weeks.
- **Full UFI Rates**: Combine historical and forecast data into a single, comprehensive view.
- **Multiple UFI Support**: Easily retrieve full data for multiple UFIs by filtering based on transport mode, market, and name.
## Installation
You can install *pypply* via pip. Make sure you have Python 3.9 or later.
```bash
pip install pypply
```
## Authentication
Authentication allows you to connect a user's Upply account to your internal app or a third party app. This process involves providing your app with a token that's generated by Upply.
If you don't already have one, please see https://developers.upply.com/docs/token-generation.
## Usage
Below are some usage examples for the main features of *pypply*. Full *pypply* documentation is available at https://developers.upply.com/docs/pypply#/ and Upply API documentation is available at https://developers.upply.com/.
### Geography Feature Usage
The geography feature enables you to retrieve latitude and longitude from location queries.
**Example**
```python
from pypply.geography import Geography
token_client = "01hp1***.69aa***"
# Create a Geography object using your development token
geography = Geography(access_token=token_client)
# Retrieve coordinates for a given query
coordinates = geography.get_lat_long(query="Paris", location_type="airport", country_code="FR")
print(f"Coordinates for Paris airport: {coordinates}")
```
### Benchmark Features Usage
The benchmark features allow you to retrieve lane benchmark rates, confidence indices, and emission data for different transport modes (air, road_emea, road_na, or sea_longterm).
**Example**
```python
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}")
```
### UFI Features Usage
The UFI features allow you to retrieve both historical and forecast UFI data. You can filter UFIs by transport mode, market, and name, and then request combined historical and forecast data.
**Example**
```python
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}")
# Retrieve forecast data for the same UFI
ufi_forecast = smart.ufi_forecast(code=ufi_code, nb_weeks=4)
print(f"UFI forecast data: {ufi_forecast}")
# Retrieve combined historical and forecast data
ufi_historical_and_forecast = smart.ufi_historical_and_forecast(code=ufi_code)
print(f"UFI historical and forecast data: {ufi_historical_and_forecast}")
```
## Contributing
We welcome issues, code and docs contributions. Please keep PRs small and focused, add tests/docs, and follow our style/linting rules.
See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide.
### Eligibility and API access
To contribute to code, you must be an **Upply customer** and your **company must have an API token**.
If you don’t have a token yet, please see https://developers.upply.com/docs/token-generation.
## License
This project is licensed under the MIT License. See the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "pypply",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "transport, upply, benchmark, freight, smart, supply-chain, api, python",
"author": null,
"author_email": "Baptiste Rebours <baptiste.rebours@upply.com>",
"download_url": "https://files.pythonhosted.org/packages/43/e1/db8059810eb9e4dd5e1f0ef5664b8fed9567b073c3160953b2dd6e112ab2/pypply-1.0.0.tar.gz",
"platform": null,
"description": "# pypply\n\n***pypply* makes it easier to use Upply API by providing a simple, well-structured Python interface for retrieving benchmark rates, UFI data, and geographic information. \nWith quick and straightforward integration \u2014 just like the Upply API \u2014 you can get up and running in minutes.\nIt handles API connections, payload processing, and error management so you can focus on building your application.**\n\n## Table of Contents\n\n- [Features](#features)\n - [Global](#global)\n - [Products](#products)\n- [Installation](#installation)\n- [Authentication](#authentication)\n- [Usage](#usage)\n - [Geography Feature Usage](#geography-feature-usage)\n - [Benchmark Features Usage](#benchmark-features-usage)\n - [UFI Features Usage](#ufi-features-usage)\n- [License](#license)\n\n## Features\n\n### Global\n- **Environments**: Easily switch between different API environments. Use the sandbox environment to develop and test your code without running out of credit, and switch to production when you need real Upply data.\n- **Payload Processing**: Automatically merge and complete client-provided payloads with default values. This helps reduce code and ensures consistency in your API requests.\n- **Validation**: Validate payload structure and input parameters using Pydantic models. This ensures that data sent to the API meets expected formats and types.\n- **Error Handling**: Robust error handling with meaningful error messages and logging. This makes debugging easier and ensures that issues are reported clearly to the user.\n\n### Products\n\n#### Geography\n- **Geocoding**: Convert a location query (such as a city, airport, or seaport) into its corresponding latitude and longitude.\n- **Seamless Integration**: Integrates with benchmark payload processing so that users do not have to supply coordinates manually.\n\n#### Benchmark\n- **Benchmark Rates**: Easily retrieve lane benchmark rates for various transport modes (air, road_emea, road_na, sea_longterm) along with their associated rates.\n- **Confidence Index**: Obtain a confidence index indicating the reliability of the benchmark result.\n- **Emissions**: Retrieve emissions data (e.g., CO\u2082, SO\u2082, NOx, etc.) as part of the benchmark response.\n- **Default Payload Support**: Use built-in default payloads so that you don't have to specify every parameter manually.\n- **Geolocation Integration**: Benchmark requests can automatically fetch latitude and longitude data, eliminating the need for users to provide coordinates explicitly.\n\n#### UFI\n- **List Available UFIs**: Easily list and filter available UFIs by transport mode, market, and name.\n- **Historical Data**: Retrieve historical UFI data for specified periods with flexible filtering options such as date ranges and number of months.\n- **Forecast Data**: Retrieve short-term forecast rates with a configurable number of forecast weeks.\n- **Full UFI Rates**: Combine historical and forecast data into a single, comprehensive view.\n- **Multiple UFI Support**: Easily retrieve full data for multiple UFIs by filtering based on transport mode, market, and name.\n\n\n\n## Installation\nYou can install *pypply* via pip. Make sure you have Python 3.9 or later.\n\n```bash\npip install pypply\n```\n\n## Authentication\nAuthentication allows you to connect a user's Upply account to your internal app or a third party app. This process involves providing your app with a token that's generated by Upply.\nIf you don't already have one, please see https://developers.upply.com/docs/token-generation.\n\n## Usage\nBelow are some usage examples for the main features of *pypply*. Full *pypply* documentation is available at https://developers.upply.com/docs/pypply#/ and Upply API documentation is available at https://developers.upply.com/.\n\n### Geography Feature Usage\nThe geography feature enables you to retrieve latitude and longitude from location queries.\n\n**Example**\n\n```python\nfrom pypply.geography import Geography\n\ntoken_client = \"01hp1***.69aa***\"\n\n# Create a Geography object using your development token\ngeography = Geography(access_token=token_client)\n\n# Retrieve coordinates for a given query\ncoordinates = geography.get_lat_long(query=\"Paris\", location_type=\"airport\", country_code=\"FR\")\nprint(f\"Coordinates for Paris airport: {coordinates}\")\n```\n\n### Benchmark Features Usage\nThe benchmark features allow you to retrieve lane benchmark rates, confidence indices, and emission data for different transport modes (air, road_emea, road_na, or sea_longterm).\n\n**Example**\n\n```python\nfrom pypply.smart import Smart\n\ntoken_client = \"01hp1***.69aa***\"\n\n# Create a Smart object with the desired API environment\nsmart = Smart(access_token=token_client, env='sandbox')\n\n# Prepare a benchmark payload\npayload = {\n \"pickup\": {\n \"latitude\": 49.475,\n \"longitude\": 0.1333328\n },\n \"delivery\": {\n \"latitude\": 27.714281,\n \"longitude\": 106.917885\n },\n \"shipment\": {\n \"container\": {\n \"unit\": \"40gp\",\n \"value\": 1\n },\n \"hazardous\": False\n },\n \"schedule\": {\"etd\": \"2024-10-25\"},\n \"pricing\": {\n \"thc\": {\n \"origin\": True,\n \"destination\": True\n },\n \"service_type\": \"dtd\"\n }\n}\n\n# Retrieve benchmark data with optional filters (e.g., rate ranges, emission types)\nbenchmark_result = smart.benchmark(\n mode='sea_longterm',\n payload=payload,\n emission_types=['co2', 'so2'],\n rate_ranges=['low_high']\n)\n\nprint(f\"Benchmark result: {benchmark_result}\")\n```\n\n### UFI Features Usage\nThe UFI features allow you to retrieve both historical and forecast UFI data. You can filter UFIs by transport mode, market, and name, and then request combined historical and forecast data.\n\n**Example**\n\n```python\nfrom pypply.smart import Smart\n\ntoken_client = \"01hp1***.69aa***\"\n\n# Create a Smart object\nsmart = Smart(access_token=token_client, env='sandbox')\n\n# Retrieve a list of UFIs (e.g., filtering by mode and market)\nufi_list = smart.ufi_list(mode='road_emea', market='spot', lang='en')\nprint(f\"Available UFIs: {ufi_list}\")\n\n# Retrieve historical data for a specific UFI code\nufi_code = list(ufi_list.keys())[0]\nufi_historical = smart.ufi_historical(code=ufi_code)\nprint(f\"UFI historical data: {ufi_historical}\")\n\n# Retrieve forecast data for the same UFI\nufi_forecast = smart.ufi_forecast(code=ufi_code, nb_weeks=4)\nprint(f\"UFI forecast data: {ufi_forecast}\")\n\n# Retrieve combined historical and forecast data\nufi_historical_and_forecast = smart.ufi_historical_and_forecast(code=ufi_code)\nprint(f\"UFI historical and forecast data: {ufi_historical_and_forecast}\")\n```\n\n## Contributing\n\nWe welcome issues, code and docs contributions. Please keep PRs small and focused, add tests/docs, and follow our style/linting rules. \nSee **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide.\n\n### Eligibility and API access\n\nTo contribute to code, you must be an **Upply customer** and your **company must have an API token**. \nIf you don\u2019t have a token yet, please see https://developers.upply.com/docs/token-generation.\n\n## License\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Makes it easier to use Upply API",
"version": "1.0.0",
"project_urls": {
"documentation": "https://developers.upply.com/docs/pypply/",
"homepage": "https://developers.upply.com/docs/pypply/",
"repository": "https://github.com/upply-labs/pypply"
},
"split_keywords": [
"transport",
" upply",
" benchmark",
" freight",
" smart",
" supply-chain",
" api",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c7acfe729a78dc31d868eeea0ee6875461cd017e415f5e97c8e0cfa9ecc7c4ce",
"md5": "d553203d16f602a34a0ae901ebdc58b8",
"sha256": "a40e11d6d3ee3862cc623acfb5ed2932cbe4a014f2cef6c37a22cf070d308877"
},
"downloads": -1,
"filename": "pypply-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d553203d16f602a34a0ae901ebdc58b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22100,
"upload_time": "2025-08-27T10:30:03",
"upload_time_iso_8601": "2025-08-27T10:30:03.355739Z",
"url": "https://files.pythonhosted.org/packages/c7/ac/fe729a78dc31d868eeea0ee6875461cd017e415f5e97c8e0cfa9ecc7c4ce/pypply-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "43e1db8059810eb9e4dd5e1f0ef5664b8fed9567b073c3160953b2dd6e112ab2",
"md5": "76b47c2122dee478ddfb2cb8f0ad1aec",
"sha256": "ab314d1333fb8d907ba8ff1b87b092e68268855d341dafc713b82bf75c68ad27"
},
"downloads": -1,
"filename": "pypply-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "76b47c2122dee478ddfb2cb8f0ad1aec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 21043,
"upload_time": "2025-08-27T10:30:04",
"upload_time_iso_8601": "2025-08-27T10:30:04.464980Z",
"url": "https://files.pythonhosted.org/packages/43/e1/db8059810eb9e4dd5e1f0ef5664b8fed9567b073c3160953b2dd6e112ab2/pypply-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 10:30:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "upply-labs",
"github_project": "pypply",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pypply"
}
JSON
