Skip to main content

​
Base URL

The API is versioned under the /api/v2026/ prefix.
EnvironmentBase URL
Localhttp://localhost:3000
Deployed (QA / Staging / Production)AWS API Gateway URL (generated by SAM per environment)
The API Gateway stage prefix (/qa, /staging, /production) is stripped automatically before the request reaches Express, so routes behave identically across all environments.

​
Authentication

No authentication is required. The API is public with no rate limiting.

​
Request format

All endpoints accept and return JSON.
  • Set Content-Type: application/json on every POST request.
  • GET endpoints do not require a request body or content-type header.
POST requests that are missing the Content-Type: application/json header return 415 Unsupported Media Type.

​
Endpoints

MethodPathDescriptionCached
POST/api/v2026/calculate-fareCalculate the fare for a tripNo
GET/api/v2026/zonesSectors with colors for map displayYes
GET/api/v2026/sectorLook up the sector for a neighborhoodYes
GET/api/v2026/barriosNeighborhoods grouped by sector (general + terminal)Yes
GET/api/v2026/rutas-especialesRoutes with a fixed special fareYes
GET/healthHealth checkNo

​
Caching

GET endpoints respond with: 
Cache-Control: public, max-age=300
The TTL defaults to 300 seconds and is configurable via the CACHE_TTL environment variable.

​
Response envelope

Every response — success or error — is wrapped in a standard envelope.

​
Success

​
success
boolean
required
Always true for successful responses.
​
timestamp
string
required
ISO 8601 UTC timestamp of when the request was processed (e.g. "2026-03-10T14:30:00.000Z").
​
request_id
string
required
UUID v4 that uniquely identifies this request. Use it when reporting issues.
​
data
object
required
The response payload. Shape varies by endpoint.

​
Example

{
  "success": true,
  "timestamp": "2026-03-10T14:30:00.000Z",
  "request_id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "data": {
    "origen": "San Fernando",
    "destino": "Centro",
    "hora_consulta": "09:30",
    "fecha_consulta": "2026-03-10",
    "fuente": "barrios.json → primer_sector",
    "tarifa": 7000,
    "tipo": "diurna",
    "sector_aplicado": "primer sector",
    "detalle": "Tarifa base primer sector diurna",
    "recargos": []
  }
}

​
Error

​
success
boolean
required
Always false for error responses.
​
timestamp
string
required
ISO 8601 UTC timestamp of when the error occurred.
​
request_id
string
required
UUID v4 identifying the failed request.
​
error
object
required
Interactive API documentation with a built-in request playground is available at /docs (Swagger UI). It reflects the OpenAPI 3.0 specification bundled with the server.

Build docs developers (and LLMs) love

Get started for freeTalk to us