Documentacao da API API Documentation

O RouteKit disponibiliza 3 ferramentas via protocolo MCP (Streamable HTTP). Voce tambem pode chama-las diretamente via JSON-RPC. RouteKit exposes 3 tools via MCP protocol (Streamable HTTP). You can also call them directly via JSON-RPC.

Indice Contents

1. Inicio Rapido (5 minutos) Quick Start (5 minutes)
2. Configuracao MCP (Claude, Cursor) MCP Setup (Claude, Cursor)
3. calculate_route
4. distance_matrix
5. optimize_routes
6. Tratamento de Erros Error Handling
7. Limites Rate Limits

1. Inicio Rapido Quick Start

Passo 1: Obtenha sua chave de API gratis em /signup Step 1: Get your free API key at /signup

Passo 2: Faca sua primeira chamada: Step 2: Make your first call:

curl -X POST https://routekit.nexterait.com.br/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "calculate_route",
      "arguments": {
        "origin_lat": -23.55,
        "origin_lon": -46.63,
        "destination_lat": -22.90,
        "destination_lon": -43.17
      }
    },
    "id": 1
  }'

Passo 3: Receba a resposta com distancia e duracao: Step 3: Get the response with distance and duration:

{
  "result": {
    "content": [{
      "text": "{\"distance_km\": 429.5, \"duration_min\": 324.7, \"geometry\": null}"
    }]
  }
}

2. Configuracao MCP MCP Setup

Claude Desktop / Claude Code

Adicione nas configuracoes MCP (Settings > MCP Servers): Add to your MCP settings (Settings > MCP Servers):

{
  "mcpServers": {
    "routekit": {
      "type": "url",
      "url": "https://routekit.nexterait.com.br/mcp",
      "headers": {
        "X-API-Key": "YOUR_KEY"
      }
    }
  }
}

Cursor

Adicione em .cursor/mcp.json: Add to .cursor/mcp.json:

{
  "mcpServers": {
    "routekit": {
      "url": "https://routekit.nexterait.com.br/mcp",
      "headers": { "X-API-Key": "YOUR_KEY" }
    }
  }
}

Python (via MCP SDK)

from mcp import Client

async with Client(url="https://routekit.nexterait.com.br/mcp",
                  headers={"X-API-Key": "YOUR_KEY"}) as client:
    result = await client.call_tool("calculate_route", {
        "origin_lat": -23.55, "origin_lon": -46.63,
        "destination_lat": -22.90, "destination_lon": -43.17,
    })
    print(result)

3. calculate_route

Calcula rota de conducao entre dois ou mais pontos usando a malha viaria real brasileira. Calculate driving route between two or more points using real Brazilian road network.

Parametros Parameters

NomeName	TipoType	ObrigatorioRequired	DescricaoDescription
origin_lat	float	SimYes	Latitude de origemStarting latitude
origin_lon	float	SimYes	Longitude de origemStarting longitude
destination_lat	float	SimYes	Latitude de destinoDestination latitude
destination_lon	float	SimYes	Longitude de destinoDestination longitude
waypoints	list[dict]	NaoNo	Paradas intermediarias, cada com "lat" e "lon"Intermediate stops, each with "lat" and "lon"
include_geometry	bool	NaoNo	Retornar polyline codificada (padrao: false)Return encoded polyline (default: false)

Resposta Response

{"distance_km": 429.5, "duration_min": 324.7, "geometry": null}

4. distance_matrix

Calcula a matriz NxN de distancia e duracao entre todos os pares de locais. Maximo 200 locais. Compute NxN distance and duration matrix between all pairs of locations. Max 200 locations.

Parametros Parameters

NomeName	TipoType	DescricaoDescription
locations	list[dict]	Cada com "lat", "lon" e "label" (opcional) Each with "lat", "lon", and optional "label"

Exemplo Example

// Input
{"locations": [
  {"lat": -23.55, "lon": -46.63, "label": "SP"},
  {"lat": -22.90, "lon": -43.17, "label": "RJ"},
  {"lat": -19.92, "lon": -43.93, "label": "BH"}
]}

// Response
{
  "locations": ["SP", "RJ", "BH"],
  "distances_km": [[0, 429.5, 586.3], [429.5, 0, 441.2], [586.3, 441.2, 0]],
  "durations_min": [[0, 324.7, 412.5], [324.7, 0, 338.1], [412.5, 338.1, 0]],
  "size": "3x3"
}

5. optimize_routes

Motor completo de otimizacao de rotas. Atribui tarefas a veiculos, sequencia paradas de forma otima e respeita todas as restricoes. Maximo 500 tarefas, 100 veiculos. Full route optimization engine. Assigns tasks to vehicles, sequences stops optimally, respects all constraints. Max 500 tasks, 100 vehicles.

Parametros de Tarefa Task Parameters

CampoField	TipoType	ObrigatorioRequired	DescricaoDescription
id	int	SimYes	ID unico da tarefaUnique task ID
lat, lon	float	SimYes	Localizacao da tarefaTask location
service_min	float	NaoNo	Duracao do servico (padrao: 15 min)Service duration (default: 15 min)
skills	list[int]	NaoNo	IDs de habilidades necessariasRequired skill IDs
priority	int	NaoNo	0-100, maior = mais importante0-100, higher = more important
time_windows	list[dict]	NaoNo	{"start": 9.0, "end": 12.0} (horas decimais){"start": 9.0, "end": 12.0} (decimal hours)
delivery	list[int]	NaoNo	Quantidades a entregar (multi-dim)Quantities to deliver (multi-dim)

Parametros de Veiculo Vehicle Parameters

CampoField	TipoType	ObrigatorioRequired	DescricaoDescription
id	int	SimYes	ID unico do veiculoUnique vehicle ID
lat, lon	float	SimYes	Local de partidaStarting location
name	str	NaoNo	Nome do motorista/veiculoDriver/vehicle name
capacity	list[int]	NaoNo	Carga maxima por dimensao (padrao: [50])Max load per dimension (default: [50])
skills	list[int]	NaoNo	Habilidades deste veiculoSkills this vehicle has
start_hour, end_hour	float	NaoNo	Janela de turno (padrao: 9.0 - 18.0)Shift window (default: 9.0 - 18.0)
max_tasks	int	NaoNo	Maximo de tarefas para este veiculoMax tasks for this vehicle
breaks	list[dict]	NaoNo	Janelas de pausa com duration_minBreak windows with duration_min
costs	dict	NaoNo	{"fixed": 0, "per_hour": 3600, "per_km": 0}

Opcoes Options

CampoField	PadraoDefault	DescricaoDescription
return_to_base	false	Veiculos retornam ao local de partidaVehicles return to starting location
exploration_level	5	Intensidade do solver 0-5 (5 = melhor qualidade)Solver intensity 0-5 (5 = best quality)

Exemplo Completo Full Example

// Input
{
  "tasks": [
    {"id": 1, "lat": -23.56, "lon": -46.65, "service_min": 30, "skills": [1],
     "time_windows": [{"start": 9.0, "end": 12.0}]},
    {"id": 2, "lat": -23.58, "lon": -46.67, "service_min": 20, "priority": 80},
    {"id": 3, "lat": -23.52, "lon": -46.61, "service_min": 15, "delivery": [2]}
  ],
  "vehicles": [
    {"id": 1, "name": "Carlos", "lat": -23.55, "lon": -46.63,
     "skills": [1, 2], "capacity": [10], "start_hour": 8.0, "end_hour": 17.0,
     "breaks": [{"id": 1, "start_hour": 12.0, "end_hour": 13.0, "duration_min": 60}]},
    {"id": 2, "name": "Maria", "lat": -23.54, "lon": -46.62,
     "capacity": [10], "start_hour": 9.0, "end_hour": 18.0}
  ],
  "return_to_base": true,
  "exploration_level": 5
}

// Response
{
  "routes": [
    {
      "vehicle_id": 1, "vehicle_name": "Carlos",
      "n_tasks": 2, "distance_km": 12.3, "travel_min": 45.2,
      "steps": [
        {"type": "start", "lat": -23.55, "lon": -46.63},
        {"type": "job", "task_id": 1, "lat": -23.56, "lon": -46.65, "arrival_min": 490.0},
        {"type": "job", "task_id": 2, "lat": -23.58, "lon": -46.67, "arrival_min": 530.0},
        {"type": "end", "lat": -23.55, "lon": -46.63}
      ]
    },
    {
      "vehicle_id": 2, "vehicle_name": "Maria",
      "n_tasks": 1, "distance_km": 5.1, "travel_min": 18.3,
      "steps": [...]
    }
  ],
  "unassigned": [],
  "summary": {
    "total_distance_km": 17.4, "total_travel_min": 63.5,
    "n_routes": 2, "n_tasks_assigned": 3, "n_unassigned": 0,
    "computing_ms": 245
  }
}

6. Tratamento de Erros Error Handling

Codigo HTTPHTTP Code	SignificadoMeaning	AcaoAction
401	Chave de API invalida ou ausenteInvalid or missing API key	Verifique o header X-API-KeyCheck X-API-Key header
403	Chave de API suspensaAPI key suspended	Verifique o status no dashboardCheck payment status in dashboard
429	Limite mensal excedidoMonthly limit exceeded	Faca upgrade ou aguarde o proximo periodoUpgrade tier or wait for next period
ToolError	Input invalido (coordenadas, campos ausentes)Invalid input (coords, missing fields)	Verifique os parametros na documentacaoCheck parameters against docs

7. Limites Rate Limits

PlanoTier	Chamadas/MesCalls/Month	PrecoPrice	Max Tarefas/ReqMax Tasks/Request	Max Locais MatrizMax Matrix Locations
GratuitoFree	50	R$ 0	500	200
Starter	1.000	R$ 500	500	200
Professional	10.000	R$ 3.000	500	200

Coordenadas devem estar dentro do Brasil: Latitude -34.0 a 6.0, Longitude -74.0 a -34.0. Coordenadas fora desta faixa retornarao um ToolError. Coordinates must be within Brazil: Latitude -34.0 to 6.0, Longitude -74.0 to -34.0. Coordinates outside this range will return a ToolError.