# TRANSCEND — Full API Reference for LLMs

> By Cargoffer — https://cargoffer.com
> Production API: https://back.transcend.cargoffer.com
> Last updated: 2026-06-10

This is the extended version of `llms.txt`. It contains every endpoint with all parameters, request/response examples, error codes, and integration patterns. For a quick overview, see [llms.txt](./llms.txt).

---

## Table of Contents

1. [Authentication & Authorization](#authentication--authorization)
2. [Rate Limits & Errors](#rate-limits--errors)
3. [Route Optimization](#1-route-optimization)
4. [Weather Intelligence](#2-weather-intelligence)
5. [Traffic](#3-traffic)
6. [Tolls & Costs](#4-tolls--costs)
7. [Fuel Stations](#5-fuel-stations)
8. [Points of Interest](#6-points-of-interest)
9. [Vehicles](#7-vehicles)
10. [Drivers](#8-drivers)
11. [HS Code Classification](#9-hs-code-classification)
12. [IAM — Auth & API Keys](#10-iam--auth--api-keys)
13. [Pricing & Plans](#pricing--plans)
14. [SDKs & MCP](#sdks--mcp-server)

---

## Authentication & Authorization

Two authentication mechanisms are supported:

### 1. JWT (user sessions)
```
Authorization: Bearer <jwt_token>
```
Returned by `POST /iam/api/auth/login`. Expires in 24h.

### 2. API Key (server-to-server)
```
x-api-key: <api_key>
```
Generated via `POST /iam/api/apikeys/`. Recommended for production integrations.

### Free Tier
100 requests/day **without any key** via the MCP server (`@transcend/mcp-server`).

---

## Rate Limits & Errors

| Plan | Daily Limit | Rate |
|------|-------------|------|
| Free | 100 req/day | 1 req/sec |
| Basic | 10,000 req/day | 10 req/sec |
| Premium | Custom | Custom |

### Error codes
| HTTP | Meaning | Action |
|------|---------|--------|
| 400 | Bad request | Check parameter types |
| 401 | Unauthorized | Check `x-api-key` header |
| 402 | Limit exceeded | Upgrade plan or wait |
| 404 | Not found | Check resource ID |
| 429 | Rate limited | Retry after `Retry-After` header |
| 500 | Server error | Retry with exponential backoff |

All errors return: `{ "error": "string", "code": "string", "details": {} }`

---

## 1. Route Optimization

### `GET /route/`
Calculate optimized route between two points with vehicle constraints and EU driving hours.

**Query parameters:**
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `origin_lat` | float | yes | Origin latitude (WGS84) |
| `origin_lon` | float | yes | Origin longitude |
| `destiny_lat` | float | yes | Destination latitude |
| `destiny_lon` | float | yes | Destination longitude |
| `vehicle` | JSON | no | `{width, height, weight, length, axleLoad, axleCount, hazmat}` |
| `driver` | JSON | no | `{hoursStatus: {remainingWeeklyHours, remainingBiweeklyHours, remainingDayHours}}` |
| `waypoints` | JSON | no | Array of `{lat, lon}` for multi-stop |
| `costingOptions` | JSON | no | `{excludeTolls, excludeHighways, useTruckRoute}` |
| `includeAllManeuverFields` | bool | no | Return full turn-by-turn |
| `language` | string | no | `es-ES`, `en-GB`, `pt-PT` (default `es-ES`) |

**Example request:**
```bash
curl "https://back.transcend.cargoffer.com/route/?origin_lat=42.2406&origin_lon=-8.7207&destiny_lat=41.3874&destiny_lon=2.1686&vehicle=%7B%22weight%22%3A40000%2C%22height%22%3A4.0%2C%22axleLoad%22%3A11500%7D&driver=%7B%22hoursStatus%22%3A%7B%22remainingWeeklyHours%22%3A56%7D%7D&includeAllManeuverFields=true" \
  -H "x-api-key: YOUR_KEY"
```

**Example response:**
```json
{
  "main": {
    "shape": "encoded_polyline_string",
    "summary": {
      "distance": 1095.2,
      "length": 1095.2,
      "time": "11h 32min",
      "timeInSeconds": 41520,
      "timeWithBreaks": "13h 18min",
      "timeWithBreaksInSeconds": 47880,
      "breakTimeInSeconds": 6360,
      "arrivalDate": "2026-06-10T22:45:00Z",
      "departureDate": "2026-06-10T09:00:00Z",
      "has_time_restrictions": false,
      "has_toll": true,
      "has_highway": true,
      "has_ferry": false,
      "cost": 184.50
    },
    "maneuvers": [
      {
        "length": 0.234,
        "time": 18,
        "bIndex": 0,
        "eIndex": 3,
        "instruction": "Sal de la calle hacia la N-550",
        "type": 1,
        "modifier": "straight",
        "streetNames": ["Rúa do Progreso"]
      }
    ],
    "stops": [
      {
        "coordinates": [42.2406, -8.7207],
        "stopType": "origin",
        "durationMinutes": 0,
        "arrivalDate": "2026-06-10T09:00:00Z",
        "departureDate": "2026-06-10T09:00:00Z"
      }
    ]
  },
  "alternatives": [],
  "has_route_limit": false
}
```

### `GET /route/api/isochrone`
Compute isochrone (reachable area in X minutes/km).

**Query parameters:** `lat`, `lon`, `km` (or `minutes`), `vehicle` (optional)

**Example:**
```bash
curl "https://back.transcend.cargoffer.com/route/api/isochrone?lat=40.4168&lon=-3.7038&km=100" \
  -H "x-api-key: YOUR_KEY"
```

**Response:** GeoJSON FeatureCollection of reachable polygons.

### `POST /route/api/saved-routes`
Save a route for later retrieval.
```json
{ "name": "Madrid-Valencia semanal", "routeData": {...}, "waypoints": [...] }
```

### `GET /route/api/saved-routes/{id}/gpx`
Export saved route as GPX file for GPS devices.

---

## 2. Weather Intelligence

### `GET /weather/current`
Current weather for a location. Source: AEMET (Spain), IPMA (Portugal), OpenWeather (rest of world).

**Query:** `lat`, `lon`, `lang` (es/en/pt)

**Response:**
```json
{
  "currentWeather": [{
    "name": "Madrid",
    "dt": 1718457600,
    "main": { "temp": 24.5, "feels_like": 25.1, "humidity": 45, "pressure": 1015 },
    "wind": { "speed": 3.5, "deg": 220 },
    "weather": [{ "id": 800, "main": "Clear", "description": "cielo claro", "icon": "01d" }],
    "dangerScore": 12
  }]
}
```

### `GET /weather/forecast`
5-day forecast with 3-hour intervals.
**Query:** `lat`, `lon`, `start` (YYYY-MM-DD), `end` (YYYY-MM-DD), `lang`

### `GET /weather/alerts/current`
Active weather alerts (rain, snow, fog, wind).
**Query:** `lat`, `lon`, `dangerLevel` (0-100, threshold for severity)

### `POST /weather/route`
Weather forecast along a route.
**Body:** `{points: [[lat, lon], ...], hours: 12}`

---

## 3. Traffic

### `GET /traffic/nearby`
Real-time traffic incidents near a point.
**Query:** `lat`, `lon`, `radius` (meters, default 25000)

**Response items:**
```json
{
  "type": "ACCIDENT",
  "severity": "MAJOR",
  "lat": 40.42,
  "lon": -3.71,
  "description": "Accidente en A-42 km 23",
  "startTime": "2026-06-10T08:00:00Z",
  "endTime": null
}
```

### `GET /traffic/radar/nearby`
Fixed and mobile speed cameras.
**Query:** `lat`, `lon`, `radius`

### `GET /traffic/blackspot/nearby`
Blackspot zones (accident-prone areas) with danger level.
**Query:** `lat`, `lon`, `minDangerLevel` (0-100)

### `POST /traffic/blackspots/path`
Blackspots along a route.
**Body:** `{points: [[lat, lon], ...]}` or `{routeId: "..."}`

---

## 4. Tolls & Costs

### `GET /tolls/costs`
Total route cost including tolls, fuel, maintenance, CO2, driving time.

**Query:**
| Param | Type | Description |
|-------|------|-------------|
| `origin` | JSON | `{lat, lng}` |
| `destination` | JSON | `{lat, lng}` |
| `with_tolls` | bool | Include toll calculation |
| `fuel_type` | string | `diesel`, `gasoline`, `electric`, `lng` |
| `consumption` | float | L/100km (optional, from vehicle) |
| `vehicle_weight` | float | kg (for toll category) |
| `axle_count` | int | Number of axles |

**Example:**
```bash
curl "https://back.transcend.cargoffer.com/tolls/costs?origin=%7B%22lat%22%3A41.39%2C%22lng%22%3A2.17%7D&destination=%7B%22lat%22%3A40.42%2C%22lng%22%3A-3.70%7D&with_tolls=true&fuel_type=diesel&vehicle_weight=18000&axle_count=5" \
  -H "x-api-key: YOUR_KEY"
```

**Response:**
```json
{
  "totalCost": 184.50,
  "breakdown": {
    "tolls": 87.20,
    "fuel": 78.30,
    "maintenance": 12.50,
    "co2Tax": 6.50
  },
  "currency": "EUR",
  "distance": 1095.2,
  "tollSegments": [
    { "name": "AP-7", "cost": 32.40, "country": "ES" }
  ]
}
```

---

## 5. Fuel Stations

### `GET /stations/nearby`
Gas stations near a point.
**Query:** `lat`, `lon`, `radius` (m), `fuel_type` (diesel_regular, diesel_premium, gasoline_95, etc.)

**Response items include:** name, brand (Repsol, Cepsa, BP, etc.), address, lat/lon, prices per fuel, opening hours, services (truck-friendly, 24h, etc.)

### `GET /stations/best-prices`
Top N cheapest stations in a country or region.
**Query:** `fuel_type`, `country` (es, pt), `limit`

### `GET /stations/province`
Stations in a Spanish province.
**Query:** `province` (Madrid, Barcelona, etc.)

### `GET /stations/getAlongPath`
Stations along a route polyline.
**Query:** `points=[[lat,lon],...]`, `radius_per_segment=10000`

---

## 6. Points of Interest

### Parking
- `GET /poi/parking/location?lat&lng&radius`
- `GET /poi/parking/zipcode?zipcode&country`
- `GET /poi/parking/province?province`

### Generic POI
- `GET /poi/search/nearby?lat&lng&radius&type=truck_stop|workshop|rest_area|shower|restaurant`

---

## 7. Vehicles

| Endpoint | Description |
|----------|-------------|
| `GET /vehicles/vehicles` | List fleet (paginated, filterable by company) |
| `POST /vehicles/vehicles` | Create vehicle (returns `_id`) |
| `GET /vehicles/vehicles/{id}` | Get vehicle details |
| `PUT /vehicles/vehicles/{id}` | Update vehicle |
| `DELETE /vehicles/vehicles/{id}` | Delete (soft) |
| `GET /vehicles/brands` | All vehicle brands |
| `GET /vehicles/models/{brandId}` | Models for a brand |
| `GET /vehicles/models/{modelId}/specs` | Technical specs (height, weight, axle load) |
| `GET /vehicles/search?q=volvo` | Fuzzy search |

**Vehicle schema (required for routing):**
```json
{
  "plate": "1234-ABC",
  "brand": "Volvo",
  "model": "FH16",
  "vehicleType": "tir",
  "weight": 18000,
  "height": 4.0,
  "width": 2.55,
  "length": 16.5,
  "axleLoad": 11500,
  "axleCount": 3,
  "fuelType": "diesel",
  "consumption": 32.5,
  "shipping_type": "dry"
}
```

---

## 8. Drivers

| Endpoint | Description |
|----------|-------------|
| `GET /drivers/` | List drivers |
| `POST /drivers/` | Create driver |
| `GET /drivers/{id}` | Get driver |
| `GET /drivers/{id}/position` | Current GPS position |
| `GET /drivers/{id}/hours` | Current driving hours status (EC 561/2006) |
| `GET /drivers/hours/driver/{cardNumber}/summary` | Tachograph summary |
| `GET /drivers/{id}/history` | Tachograph records (last 28 days) |
| `GET /drivers/{id}/compliance` | EU compliance status (working time, breaks) |
| `PUT /drivers/{id}/position` | Update position (from mobile app) |

**Hours status response:**
```json
{
  "remainingWeeklyHours": 32.5,
  "remainingBiweeklyHours": 67.0,
  "remainingDayHours": 6.5,
  "needsBreak": false,
  "exceedsDaily": false,
  "lastRestStart": "2026-06-09T22:00:00Z"
}
```

---

## 9. HS Code Classification

HS (Harmonized System) codes for customs and merchandise classification.

- `GET /hscode/` — Full hierarchical HS structure
- `GET /hscode/search?q=algodon` — Search by description (Spanish/English)
- `GET /hscode/{chapter}/{heading}/{subheading}` — Specific code details
- `GET /profiles/structure` — Same as HS structure
- `GET /profiles/search?q=atun` — Search by product name

**ADR (Hazardous Materials) detection:**
The `/route` endpoint accepts `merchandise.hsCode` and `merchandise.isADR` flags. When `isADR: true`, Valhalla excludes tunnels with hazmat restrictions.

---

## 10. IAM — Auth & API Keys

### `POST /iam/api/auth/register`
```json
{ "email": "user@example.com", "password": "min8chars", "companyCif": "B12345678", "name": "Acme SL" }
```
Returns: `{ user: {...}, token: "jwt..." }`

### `POST /iam/api/auth/login`
```json
{ "email": "user@example.com", "password": "..." }
```
Returns: `{ token: "jwt...", user: {...} }`

### `POST /iam/api/apikeys/`
Authenticated. Creates a new API key.
Returns: `{ key: "tk_live_...", name: "Production" }`

### `GET /iam/api/apikeys/verify?key=...`
Public. Verifies an API key and returns its plan/limits.

---

## Pricing & Plans

| Plan | Price | Daily Limit | Rate | Features |
|------|-------|-------------|------|----------|
| **Free** | 0 EUR | 100 req/day | 1 rps | All endpoints, MCP server |
| **Basic** | 29 EUR/mo | 10,000 req/day | 10 rps | + webhooks, priority support |
| **Premium** | Contact | Custom | Custom | + SLA, dedicated support |

Upgrade via Stripe Checkout (web only). API responses include `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers.

---

## SDKs & MCP Server

### MCP Server (AI Agents — Claude, GPT, etc.)
```bash
npx @transcend/mcp-server
```
8 tools: `calculate_route`, `get_weather`, `get_traffic`, `calculate_tolls`, `find_stations`, `find_pois`, `manage_vehicles`, `manage_drivers`. **No API key needed for free tier.**

### JavaScript/TypeScript SDK
```bash
npm install @transcend/sdk
```
```typescript
import { TranscendClient } from '@transcend/sdk';
const client = new TranscendClient({ apiKey: process.env.TRANSCEND_KEY });
const route = await client.route.calculate({
  origin: { lat: 40.4168, lon: -3.7038 },
  destination: { lat: 41.3874, lon: 2.1686 },
  vehicle: { weight: 18000, height: 4.0 }
});
```

### Python SDK
```bash
pip install transcend-sdk
```
```python
from transcend import TranscendClient
client = TranscendClient(api_key="...")
route = client.route.calculate(origin=(40.4168, -3.7038), destination=(41.3874, 2.1686), vehicle={"weight": 18000})
```

### curl (no SDK)
```bash
curl -H "x-api-key: YOUR_KEY" "https://back.transcend.cargoffer.com/route/?origin_lat=40.4168&origin_lon=-3.7038&destiny_lat=41.3874&destiny_lon=2.1686"
```

---

## Real-World Use Cases

1. **Fleet routing app**: `/route/` + `/drivers/{id}/hours` to ensure EU compliance
2. **Fuel optimization**: `/tolls/costs` + `/stations/best-prices` to find cheapest refuel along route
3. **Weather-aware ETA**: `/route/` + `/weather/forecast` to adjust delivery times
4. **ADR compliance**: `/route/` with `merchandise.isADR: true` excludes hazmat-restricted tunnels
5. **Multi-stop delivery**: `/route/` with `waypoints` array for distribution routes
6. **Cost estimation for clients**: `/tolls/costs` to quote delivery prices

---

## Geographic Coverage

- **Best coverage**: Spain, Portugal, France, Germany, Italy, Andorra
- **Working**: Rest of EU (no real-time fuel prices, no live traffic)
- **Limited**: Outside EU (routing only, no fuel/traffic)

OSM data updated weekly. Valhalla graph built from Geofabrik extracts.

---

## Support

- Email: support@transcend.cargoffer.com
- Docs: https://transcend.cargoffer.com/docs
- Status: https://status.cargoffer.com
- GitHub: https://github.com/cargoffer
- Web: https://transcend.cargoffer.com