Tu Lugar API

Início rápido

Não precisa de API key. Teste agora mesmo:

# Search apartments for sale in Asunción
curl "https://tulugar.com/api/v1/listings?city=Asunci%C3%B3n&listing_type=sale&property_type=apartment&limit=3"

# Get market summary
curl "https://tulugar.com/api/v1/market/summary?city=Asunci%C3%B3n"

# List all countries
curl "https://tulugar.com/api/v1/locations/countries"

Fluxos comuns

Encadeie chamadas à API para realizar tarefas típicas. Este exemplo encontra apartamentos à venda em um bairro específico.

curl "https://tulugar.com/api/v1/locations/countries"
# Response: [{ "name": "Paraguay", "listing_count": 2500 }, ...]

curl "https://tulugar.com/api/v1/locations/cities?country=Paraguay"
# Response: [{ "name": "Asunción", "listing_count": 1200 }, ...]

curl "https://tulugar.com/api/v1/locations/neighborhoods?city=Asunci%C3%B3n"
# Response: [{ "name": "Villa Morra", "listing_count": 245 }, ...]

curl "https://tulugar.com/api/v1/listings?city=Asunci%C3%B3n&neighborhood=Villa+Morra&listing_type=sale&property_type=apartment&limit=10"

Formato de resposta

{
  "data": [ ... ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-10T..."
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "city is required",
    "status": 400
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Autenticação

Os endpoints de leitura são públicos, sem key. Os endpoints da API de agente (escrita) exigem um token de acesso OAuth 2.1 (authorization code + PKCE). A forma mais simples de obter um é adicionar o conector do Tu Lugar no Claude ou em outro cliente MCP: ele executa todo o fluxo para você. Integrações diretas usam o fluxo padrão descrito abaixo. Envie o token como cabeçalho bearer:

Authorization: Bearer YOUR_ACCESS_TOKEN

Scopes

Fluxo de autorização (integrações diretas)

1. Obtenha a metadata de descoberta a partir dos endpoints .well-known abaixo.
2. Registre um cliente via Dynamic Client Registration (RFC 7591) em POST /api/oauth/register.
3. Envie o usuário para /api/oauth/authorize com um desafio PKCE S256; ele faz login e dá o consentimento.
4. Troque o código retornado em POST /api/oauth/token por um token de acesso + refresh.
5. Chame a API com Authorization: Bearer. Os refresh tokens rotacionam a cada uso.

Endpoints de descoberta

Imóveis

Busque, filtre e obtenha imóveis.

Projetos

Projetos em desenvolvimento (torres residenciais, condomínios fechados, etc.). Por padrão, só são retornados os projetos com unidades disponíveis, ordenados com os verificados primeiro.

Empresas

Imobiliárias e incorporadoras.

Corretores

Corretores e profissionais do setor.

Localizações

Países, cidades e bairros com a contagem de anúncios.

Dados de mercado

Estatísticas agregadas de mercado e dados de aluguel por temporada.

Calculadoras

Calculadoras de finanças imobiliárias, independentes de moeda e adaptadas ao Paraguai. Feitas para uso por IA; sem autenticação.

API de agente (escrita)

Endpoints autenticados para que os corretores criem e gerenciem seus próprios anúncios. Todos os endpoints de escrita exigem um token bearer OAuth 2.1 com o scope indicado em cada linha (ver Autenticação). As escritas de anúncios passam por moderação automática antes de ficarem públicas.

Limites e uso justo