> ## Documentation Index
> Fetch the complete documentation index at: https://dev.igps.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Querying Vehicle Positions with the iGps API

> Learn how to use iGps batch queries to retrieve GPS positions for up to 50 vehicles in a single API call, reducing latency and API overhead.

O endpoint de posições da iGps aceita até 50 números de chassi por requisição. Agrupar suas consultas reduz o número de chamadas à API e diminui a latência total para consultas em escala de frota.

## Formato da Requisição em Lote

Inclua múltiplos números de chassi como um array no campo `chassis` do corpo da sua requisição. Tenha em mente as seguintes regras:

* Cada chassi deve ter exatamente 17 caracteres
* Mínimo de 1, máximo de 50 por requisição
* Duplicatas são permitidas, mas resultam em respostas redundantes

```json theme={null}
{
  "chassis": [
    "VIN00000000000001",
    "VIN00000000000002",
    "VIN00000000000003"
  ]
}
```

## Dividindo Frotas Grandes

Quando sua frota excede 50 veículos, divida a lista completa de chassis em blocos de 50 e envie uma requisição por bloco. Junte os arrays `resultados` de cada resposta para montar um conjunto de dados completo.

```python theme={null}
import requests

def chunk(lst, size):
    for i in range(0, len(lst), size):
        yield lst[i:i + size]

all_chassis = ["VIN" + str(i).zfill(14) for i in range(1, 151)]  # 150 veiculos

results = []
for batch in chunk(all_chassis, 50):
    resp = requests.post(
        "https://api.igps.com.br/api/v1/veiculos/posicoes",
        headers={"Authorization": f"Bearer {token}"},
        json={"chassis": batch}
    )
    results.extend(resp.json()["resultados"])

print(f"Posicoes obtidas para {len(results)} veiculos")
```

## Resultados Parciais

Uma resposta `200 OK` é retornada mesmo se alguns veículos no lote não forem encontrados. Entradas em que `status` for `nao_encontrado` não incluirão os campos `latitude`, `longitude` ou `timestamp`. Sempre verifique o campo `status` de cada resultado individual em vez de presumir que todos os veículos foram localizados.

```json theme={null}
{
  "resultados": [
    {
      "chassi": "VIN00000000000001",
      "timestamp": "2024-06-01 12:00:00",
      "latitude": -23.5505,
      "longitude": -46.6333,
      "status": "ok"
    },
    {
      "chassi": "VIN00000000000002",
      "status": "nao_encontrado"
    }
  ]
}
```

<Info>
  Requisições com mais de 50 números de chassi retornarão um erro 400 Bad Request. Sempre divida listas grandes em lotes de 50 ou menos.
</Info>