Metadata-Version: 2.5
Name: esgo
Version: 0.1.0
Summary: Official Python SDK for the ESGO API (empty-run matching for road freight)
Project-URL: Homepage, https://es-go.de/developers
Project-URL: Documentation, https://api.es-go.de/v1/docs
Project-URL: Source, https://github.com/ESGO-Logistics/esgo-python
Project-URL: Changelog, https://github.com/ESGO-Logistics/esgo-python/blob/main/CHANGELOG.md
Author: ESGO Logistics UG (haftungsbeschränkt)
License-Expression: MIT
License-File: LICENSE
Keywords: api,esgo,freight,logistics,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: attrs>=22.2.0
Requires-Dist: httpx<1,>=0.23
Provides-Extra: dev
Requires-Dist: openapi-python-client==0.29.1; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# ESGO Python SDK

*[Deutsche Version weiter unten](#esgo-python-sdk-deutsch)*

Official Python client for the [ESGO API](https://es-go.de/developers): find
matching empty-run capacity for road freight and publish open transport
requests from your TMS or ERP.

> **Alpha.** Covers all endpoints of API v1: key info, matching search and open
> requests. The SDK may still change before 1.0; see [CHANGELOG.md](CHANGELOG.md).

## Installation

```sh
pip install esgo
```

Requires Python 3.11 or newer.

## Access

API keys are issued by ESGO; there is no self-service sign-up yet. Request
access at [es-go.de/developers](https://es-go.de/developers). Keep your key
secret and never commit it to a repository.

## Usage

Set the key once and call the API through the `esgo` module, like the `stripe`
package:

```python
import esgo

esgo.api_key = "esgo_live_..."   # or set the ESGO_API_KEY environment variable

result = esgo.matches.search(
    origin="47057 Duisburg",
    destination="80331 München",
    weight_kg=12000,
    loading_meters=4.8,
)
for match in result.data:
    print(match.route_id, match.departure_window.start, match.price_estimate_eur, match.booking_url)
```

Or create a client, which is useful when you work with several keys:

```python
import esgo

with esgo.Client(api_key="esgo_live_...") as client:
    me = client.me.retrieve()
    print(me.account_role, [(q.name, q.remaining) for q in me.quotas])
```

### Open requests

Publish a transport request; ESGO matches it against carriers' empty runs:

```python
from datetime import datetime

request = esgo.open_requests.create(
    origin="47057 Duisburg",
    destination="80331 München",
    weight_kg=12000,
    loading_meters=4.8,
    cargo_type="Paletten",
    time_windows=[{"start": datetime(2026, 11, 3, 8), "end": datetime(2026, 11, 3, 16)}],
)
print(request.id, request.matches_found)

for match in esgo.open_requests.list_matches(request.id).data:
    print(match.route_id, match.match_score)
```

Times are local time Europe/Berlin. Responses are typed objects from
`esgo.models`; call `.to_dict()` on any of them for a plain `dict`.

| Method | Endpoint |
|---|---|
| `me.retrieve()` | `GET /v1/me` |
| `matches.search(**params)` | `POST /v1/matches/search` |
| `open_requests.create(**params)` | `POST /v1/open-requests` |
| `open_requests.list_matches(request_id)` | `GET /v1/open-requests/{request_id}/matches` |

All parameters are described in the [API reference](https://api.es-go.de/v1/docs).

## Errors

Every API error raises a subclass of `esgo.APIError` with the fields of the
ESGO error envelope:

```python
try:
    esgo.me.retrieve()
except esgo.RateLimitError as e:
    print("Try again in", e.retry_after, "seconds")
except esgo.APIError as e:
    print(e.status, e.code, e.message, e.param, e.request_id)
```

| Exception | HTTP status |
|---|---|
| `InvalidRequestError` | 400, 422 |
| `AuthenticationError` | 401 |
| `PermissionDeniedError` | 403 |
| `NotFoundError` | 404 |
| `RateLimitError` | 429 |
| `ServiceUnavailableError` | 503 |
| `InternalServerError` | other 5xx |
| `APIConnectionError` | network error, no response |

## Links

- API reference: [api.es-go.de/v1/docs](https://api.es-go.de/v1/docs)
- OpenAPI spec: [api.es-go.de/v1/openapi.json](https://api.es-go.de/v1/openapi.json)
- Changelog: [CHANGELOG.md](CHANGELOG.md)

## License

MIT, see [LICENSE](LICENSE).

---






# ESGO Python SDK (Deutsch)


Dies ist der offizielle Python-Client für die [ESGO API](https://es-go.de/developers):


Hier ein kleines Vorwort, weiter unten kommt der eigentlich wichtige Teil (17.10.2026):

Hi, mein Name ist Ivo Wundling, ich bin (stand heute) 20 Jahre alt und bin einer der Geschäftsführer der ESGO Logistics UG (haftungsbeschränkt) aus Bonn. 
Am 19 Mai 2025 haben wir begonnen, die Plattform ESGO zu entwickeln. Begonnen hat es über einen kleinen Prototypen zum Spaß, und über die Monate wurde daraus nach Pitches u.a. vor der NRW.Bank eine riesige SaaS-Enterprise Plattform (okay fairerweise wenn man jetzt nur die v.0.0.1 liest dann kommt das nicht wirklich so rüber da müsst ihr mir jz einfach vertrauen, bzw sobald das hier jemand liest sind weitaus mehr Schnistellen öffentlich hier verfügbar).

Hier ist der Standard Satz über ESGO, welchen ich immer gerne nutze, damit jeder direkt weiss was wir machen:
ESGO ist eine KI-Plattform zur automatisierten Erkennung, Vermittlung und Monetarisierung von LKW-Leerfahrten.

Jetzt weiss man circa um was es geht, nämlich um Leerfahrten Vermittlung. Vermittlung ist dabei ein wichtiges Wort, weil wir als Plattform Handelsmakler sind (nach §93 HGB) das ist wichtig für Spediteure, da diese somit die Preishoheit behalten. Denn digitale Speditionendrücken über Algorithmen die Preise und Spediteure werden gleichzeitig zur rein ausführenden Instanz.

Allgemein kann man sagen, dass wir versuchen mit ESGO die größten Probleme der Logistik zu lösen. Dazu gehören bspw. der hohe Margendruck, entstehend durch digitale Speditionen, aber auch hohe Energie & Spritkosten, Maut, Fahrermangel und vielem mehr. 

Kein Wunder dass in so ziemlich jeder Statistik die Speditions bzw. Logistikbranche immer knallend auf dem traurigen letzten (bzw. im negativem Sinne den ersten) Platz ergattert. Einige der vielen Vorzeigebeispiele sind die Insolvenzstatistik, die Zahlungsausfallstatistik sowie die Margenstatistiken.

Aktuell bootsstrappen wir die Plattform mit selbstständigen Vertrieberler, sobald das hier allerdings jemand wirklich liest, lässt sich davon ausgehen dass dies mittlerweile nicht mehr der Fall ist.

Dazu kommen wir auch eigentlich langsam zum technischen Teil, weil wenn das hier jemand liest bedeutet dass auch dass dieser jemand (ja genau du! der das hier liest) ESGO in sein Produkt bzw. Backend eines Produktes einbauen will. (oder muss lol)

Dann kommen wir mal zum eigentlichen Spass, was macht diese Python SDK überhaupt?

Damit Spediteure und Verlader sowie ERP & TMS Systeme ESGO auch per API Anbinden können, gibts hier einen python Client welcher als Thin Wrapper agiert. Er basiert auf der openapi.json, diese findest du unter https://es-go.de/developers bzw. unter https://api.es-go.de/v1/openapi.json

Die meisten TMS/ERP systeme sind auch nicht in python, deswegen kann es gut sein dass das hier niemand jemals lesen wird, aber python import esgo hat crazy viel Aura, und der Name war frei deswegen konnte ich nicht widerstehen. Ansonsten sind in Arbeit noch das gleiche für TypeScript/JavaScript & C#.
Sollte die SDK unzureichend sein oder nicht dokumentiert genug (entschuldige ich mich erstmal im Vorraus) und dann gibts alternativ immer die openapi.json für alle frei zugänglich


Viel gerede von mir (es ist grad 0 Uhr das ganz normal zu der Zeit) und jetzt zum eigentlichen technischen Teil, wenns irgendwo zu fragen gibt einfach nen Issue anlegen oder mir auf LinkedIn schreiben (https://www.linkedin.com/in/ivo-wundling-708068272/)

LG Ivo


> **Alpha.** Deckt alle Endpunkte der API v1 ab: Schlüssel-Infos,
> Matching-Suche und offene Transportanfragen. Bis Version 1.0 kann sich das SDK
> noch ändern, siehe [CHANGELOG.md](CHANGELOG.md).

## Installation

```sh
pip install esgo
```

Erfordert Python 3.11 oder neuer.

## Zugang

API-Keys werden direkt von ESGO vergeben; eine Self-Service-Registrierung gibt
es aktuell noch nicht. Der Zugang kann unter
[es-go.de/developers](https://es-go.de/developers) angefragt werden. Halte
deinen Key geheim und committe ihn niemals in ein Repository. (logisch nh)

## Verwendung

Hinterlege den Key einmalig und rufe die API direkt über das `esgo`-Modul auf, alles ist analog zum `stripe`-Paket:

```python
import esgo

esgo.api_key = "esgo_live_..."   # oder über die Umgebungsvariable ESGO_API_KEY setzen

result = esgo.matches.search(
    origin="47057 Duisburg",
    destination="80331 München",
    weight_kg=12000,
    loading_meters=4.8,
)
for match in result.data:
    print(match.route_id, match.departure_window.start, match.price_estimate_eur, match.booking_url)
```

Alternativ kann eine eigene Client-Instanz erstellt werden (praktisch, wenn mit
mehreren Keys parallel gearbeitet wird):

```python
import esgo

with esgo.Client(api_key="esgo_live_...") as client:
    me = client.me.retrieve()
    print(me.account_role, [(q.name, q.remaining) for q in me.quotas])
```

### Offene Transportanfragen

Eine Anfrage einstellen; ESGO gleicht sie mit den Leerfahrten der Spediteure ab:

```python
from datetime import datetime

request = esgo.open_requests.create(
    origin="47057 Duisburg",
    destination="80331 München",
    weight_kg=12000,
    loading_meters=4.8,
    cargo_type="Paletten",
    time_windows=[{"start": datetime(2026, 11, 3, 8), "end": datetime(2026, 11, 3, 16)}],
)
print(request.id, request.matches_found)

for match in esgo.open_requests.list_matches(request.id).data:
    print(match.route_id, match.match_score)
```

Zeiten sind Ortszeit Europe/Berlin. Antworten sind typisierte Objekte aus
`esgo.models`; `.to_dict()` liefert jeweils ein normales `dict`.

| Methode | Endpunkt |
|---|---|
| `me.retrieve()` | `GET /v1/me` |
| `matches.search(**params)` | `POST /v1/matches/search` |
| `open_requests.create(**params)` | `POST /v1/open-requests` |
| `open_requests.list_matches(request_id)` | `GET /v1/open-requests/{request_id}/matches` |

Alle Parameter stehen in der [API-Referenz](https://api.es-go.de/v1/docs).

## Fehlerbehandlung

Jeder API-Fehler wirft eine Subklasse von `esgo.APIError`, die alle Felder der
ESGO-Fehlerantwort enthält:

```python
try:
    esgo.me.retrieve()
except esgo.RateLimitError as e:
    print("Erneuter Versuch in", e.retry_after, "Sekunden möglich")
except esgo.APIError as e:
    print(e.status, e.code, e.message, e.param, e.request_id)
```

| Exception | HTTP-Status |
|---|---|
| `InvalidRequestError` | 400, 422 |
| `AuthenticationError` | 401 |
| `PermissionDeniedError` | 403 |
| `NotFoundError` | 404 |
| `RateLimitError` | 429 |
| `ServiceUnavailableError` | 503 |
| `InternalServerError` | andere 5xx |
| `APIConnectionError` | Netzwerkfehler, keine Antwort |

## Links

- API-Referenz: [api.es-go.de/v1/docs](https://api.es-go.de/v1/docs)
- OpenAPI-Spezifikation: [api.es-go.de/v1/openapi.json](https://api.es-go.de/v1/openapi.json)
- Changelog: [CHANGELOG.md](CHANGELOG.md)

## Lizenz

MIT, siehe [LICENSE](LICENSE).