Documentação da API

v1.0 REST API
Visão Geral da API

A API XPosition permite integração completa com nossa plataforma de crowdsourcing de dados viários. Através dela, você pode:

  • Coletar dados: Enviar informações sobre elementos viários
  • Consultar dados: Buscar elementos por localização, tipo, status, etc.
  • Validar elementos: Participar do sistema de validação comunitária
  • Exportar dados: Obter dados em diferentes formatos (JSON, CSV)
  • Analytics: Acessar estatísticas e relatórios
Base URL
https://xposition.com/api
Autenticação
X-API-Key: sua-chave-aqui
Autenticação

Todas as requisições à API devem incluir uma chave de API válida no header:

X-API-Key: xp_beta_2024
Nota: A chave de exemplo xp_beta_2024 é para testes. Para produção, entre em contato conosco.
Endpoints da API
POST /api/coleta

Registra uma nova coleta de elemento viário

Requisição:
{
  "dados_geograficos": {
    "latitude": -23.5505,
    "longitude": -46.6333,
    "endereco_cidade": "São Paulo",
    "endereco_estado": "SP",
    "endereco_rua": "Rua da Consolação"
  },
  "elemento": {
    "tipo": "lombada",
    "descricao": "Lombada próxima ao semáforo"
  },
  "colaborador": {
    "colaborador_id": "user001",
    "colaborador_nome": "João Silva"
  }
}
Resposta:
{
  "status": "success",
  "message": "Coleta registrada com sucesso",
  "id": 1234,
  "timestamp": "2024-01-15T10:30:00Z"
}
GET /api/dados

Consulta coletas com filtros opcionais

Parâmetros de Query:
Parâmetro Tipo Descrição Exemplo
tipo_elemento string Filtrar por tipo lombada
cidade string Filtrar por cidade São Paulo
status_validacao string Filtrar por status validado
bbox string Bounding box -23.6,-46.7,-23.5,-46.6
page int Página 1
per_page int Itens por página 100
Exemplo de Requisição:
GET /api/dados?tipo_elemento=lombada&cidade=São Paulo&page=1&per_page=50
Resposta:
{
  "status": "success",
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1247,
    "pages": 25
  }
}
GET /api/analytics

Retorna estatísticas gerais do sistema

Resposta:
{
  "status": "success",
  "analytics": {
    "total_coletas": 15432,
    "total_colaboradores": 234,
    "score_medio_confiabilidade": 0.78,
    "tipos_elementos": [
      {"tipo": "lombada", "count": 5423},
      {"tipo": "parada_obrig", "count": 3210}
    ],
    "status_validacao": [
      {"status": "validado", "count": 8765},
      {"status": "coletado", "count": 4321}
    ]
  }
}
POST /api/validacao/{id}

Valida um elemento específico

Requisição:
{
  "acao": "validar"
}

Ações disponíveis: validar, rejeitar, confirmar

Resposta:
{
  "status": "success",
  "message": "Elemento validar com sucesso",
  "coleta": {
    "id": 1234,
    "status_validacao": "validado",
    "score_confiabilidade": 0.85
  }
}
GET /api/export

Exporta dados em diferentes formatos

Parâmetros:
  • format: json ou csv
  • Todos os parâmetros de filtro do /api/dados
Exemplo:
GET /api/export?format=csv&tipo_elemento=lombada
Resposta:

Arquivo CSV ou JSON com os dados solicitados

Códigos de Erro
Código Descrição Exemplo
400 Bad Request Dados inválidos na requisição
401 Unauthorized API Key inválida ou ausente
404 Not Found Recurso não encontrado
429 Too Many Requests Limite de rate limit excedido
500 Internal Server Error Erro interno do servidor
Rate Limiting

A API possui os seguintes limites de taxa:

  • Coleta: 100 requisições por minuto
  • Consulta: 200 requisições por minuto
  • Analytics: 100 requisições por minuto
  • Export: 10 requisições por minuto
Os limites são por chave de API. Para limites maiores, entre em contato conosco.
Exemplos de Código 
import requests

# Configuração
API_KEY = "xp_beta_2024"
BASE_URL = "https://xposition.com/api"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Consultar dados
response = requests.get(
    f"{BASE_URL}/dados",
    headers=headers,
    params={
        "tipo_elemento": "lombada",
        "cidade": "São Paulo",
        "per_page": 50
    }
)

data = response.json()
print(f"Total de coletas: {data['pagination']['total']}")

# Registrar nova coleta
coleta_data = {
    "dados_geograficos": {
        "latitude": -23.5505,
        "longitude": -46.6333,
        "endereco_cidade": "São Paulo"
    },
    "elemento": {
        "tipo": "lombada",
        "descricao": "Lombada próxima ao semáforo"
    },
    "colaborador": {
        "colaborador_id": "user001",
        "colaborador_nome": "João Silva"
    }
}

response = requests.post(
    f"{BASE_URL}/coleta",
    headers=headers,
    json=coleta_data
)

if response.status_code == 201:
    print("Coleta registrada com sucesso!")

const API_KEY = "xp_beta_2024";
const BASE_URL = "https://xposition.com/api";

const headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
};

// Consultar dados
async function consultarDados() {
    const response = await fetch(`${BASE_URL}/dados?tipo_elemento=lombada&cidade=São Paulo`, {
        headers: headers
    });
    
    const data = await response.json();
    console.log(`Total de coletas: ${data.pagination.total}`);
    return data;
}

// Registrar nova coleta
async function registrarColeta() {
    const coletaData = {
        dados_geograficos: {
            latitude: -23.5505,
            longitude: -46.6333,
            endereco_cidade: "São Paulo"
        },
        elemento: {
            tipo: "lombada",
            descricao: "Lombada próxima ao semáforo"
        },
        colaborador: {
            colaborador_id: "user001",
            colaborador_nome: "João Silva"
        }
    };
    
    const response = await fetch(`${BASE_URL}/coleta`, {
        method: "POST",
        headers: headers,
        body: JSON.stringify(coletaData)
    });
    
    if (response.ok) {
        console.log("Coleta registrada com sucesso!");
    }
}

# Consultar dados
curl -X GET "https://xposition.com/api/dados?tipo_elemento=lombada&cidade=São Paulo" \
  -H "X-API-Key: xp_beta_2024"

# Registrar nova coleta
curl -X POST "https://xposition.com/api/coleta" \
  -H "X-API-Key: xp_beta_2024" \
  -H "Content-Type: application/json" \
  -d '{
    "dados_geograficos": {
      "latitude": -23.5505,
      "longitude": -46.6333,
      "endereco_cidade": "São Paulo"
    },
    "elemento": {
      "tipo": "lombada",
      "descricao": "Lombada próxima ao semáforo"
    },
    "colaborador": {
      "colaborador_id": "user001",
      "colaborador_nome": "João Silva"
    }
  }'

# Obter analytics
curl -X GET "https://xposition.com/api/analytics" \
  -H "X-API-Key: xp_beta_2024"

# Exportar dados em CSV
curl -X GET "https://xposition.com/api/export?format=csv&tipo_elemento=lombada" \
  -H "X-API-Key: xp_beta_2024" \
  -o coletas_lombadas.csv
Suporte

Precisa de ajuda? Entre em contato conosco: