iptuapi 2.0.0

SDK oficial para a IPTU API - Dados de IPTU de São Paulo, Belo Horizonte e Recife

IPTU API - Python SDK

SDK oficial Python para integração com a IPTU API. Acesso a dados de IPTU de mais de 10 cidades brasileiras.

Instalacao

pip install iptuapi

Uso Rapido

from iptuapi import IPTUClient

client = IPTUClient("sua_api_key")

# Consulta por endereco
resultado = client.consulta_endereco("Avenida Paulista", "1000")
print(resultado)

# Consulta por SQL (Starter+)
dados = client.consulta_sql("100-01-001-001")

Configuracao

Cliente Basico

from iptuapi import IPTUClient

client = IPTUClient("sua_api_key")

Configuracao Avancada

from iptuapi import IPTUClient, ClientConfig, RetryConfig
import logging

# Configurar logging
logging.basicConfig(level=logging.DEBUG)

# Configuracao de retry
retry_config = RetryConfig(
    max_retries=5,
    initial_delay=1.0,
    max_delay=30.0,
    backoff_factor=2.0,
    retryable_status_codes=[429, 500, 502, 503, 504]
)

# Configuracao do cliente
config = ClientConfig(
    base_url="https://iptuapi.com.br/api/v1",
    timeout=60.0,
    retry_config=retry_config
)

client = IPTUClient("sua_api_key", config)

Uso com Context Manager

with IPTUClient("sua_api_key") as client:
    resultado = client.consulta_endereco("Avenida Paulista", "1000")

Cliente Assincrono

import asyncio
from iptuapi import AsyncIPTUClient

async def main():
    async with AsyncIPTUClient("sua_api_key") as client:
        resultado = await client.consulta_endereco("Avenida Paulista", "1000")
        print(resultado)

asyncio.run(main())

Endpoints da API

Consultas (Todos os Planos)

# Consulta por endereco
resultado = client.consulta_endereco(
    logradouro="Avenida Paulista",
    numero="1000",
    cidade="sp"
)

# Consulta por CEP
resultado = client.consulta_cep("01310-100", cidade="sp")

# Consulta por coordenadas (zoneamento)
resultado = client.consulta_zoneamento(latitude=-23.5505, longitude=-46.6333)

Consultas Avancadas (Starter+)

# Consulta por numero SQL
resultado = client.consulta_sql("100-01-001-001", cidade="sp")

# Historico de valores IPTU
historico = client.dados_iptu_historico("100-01-001-001", cidade="sp")

# Consulta CNPJ
empresa = client.dados_cnpj("12345678000100")

# Correcao monetaria IPCA
corrigido = client.dados_ipca_corrigir(
    valor=100000,
    data_origem="2020-01",
    data_destino="2024-01"
)

Valuation (Pro+)

# Estimativa de valor de mercado
avaliacao = client.valuation_estimate({
    "area_terreno": 250,
    "area_construida": 180,
    "bairro": "Pinheiros",
    "zona": "ZM",
    "tipo_uso": "Residencial",
    "tipo_padrao": "Medio",
    "ano_construcao": 2010
})
print(f"Valor estimado: R$ {avaliacao['valor_estimado']:,.2f}")

# Buscar comparaveis
comparaveis = client.valuation_comparables(
    bairro="Pinheiros",
    area_min=150,
    area_max=250,
    cidade="sp",
    limit=10
)

Batch Operations (Enterprise)

# Valuation em lote (ate 100 imoveis)
imoveis = [
    {"area_terreno": 250, "area_construida": 180, "bairro": "Pinheiros"},
    {"area_terreno": 300, "area_construida": 200, "bairro": "Moema"},
]
resultados = client.valuation_batch(imoveis)

Tratamento de Erros

from iptuapi import (
    IPTUClient,
    IPTUAPIError,
    AuthenticationError,
    ForbiddenError,
    NotFoundError,
    RateLimitError,
    ValidationError,
    ServerError,
    TimeoutError,
    NetworkError
)

client = IPTUClient("sua_api_key")

try:
    resultado = client.consulta_endereco("Rua Teste", "100")
except AuthenticationError as e:
    print(f"API Key invalida: {e}")
except ForbiddenError as e:
    print(f"Plano nao autorizado: {e.required_plan}")
except NotFoundError as e:
    print(f"Imovel nao encontrado: {e}")
except RateLimitError as e:
    print(f"Rate limit excedido. Retry em {e.retry_after}s")
except ValidationError as e:
    print(f"Parametros invalidos: {e.errors}")
except ServerError as e:
    print(f"Erro no servidor (retryable): {e}")
except TimeoutError as e:
    print(f"Timeout apos {e.timeout}s")
except NetworkError as e:
    print(f"Erro de conexao: {e}")
except IPTUAPIError as e:
    print(f"Erro generico: {e}, Request ID: {e.request_id}")

Propriedades dos Erros

try:
    resultado = client.consulta_endereco("Rua Teste", "100")
except IPTUAPIError as e:
    print(f"Status Code: {e.status_code}")
    print(f"Request ID: {e.request_id}")
    print(f"Retryable: {e.is_retryable}")

Rate Limiting

# Verificar rate limit apos requisicao
rate_limit = client.rate_limit
if rate_limit:
    print(f"Limite: {rate_limit.limit}")
    print(f"Restantes: {rate_limit.remaining}")
    print(f"Reset em: {rate_limit.reset_at}")

# ID da ultima requisicao (util para suporte)
print(f"Request ID: {client.last_request_id}")

Modelos de Dados

from iptuapi.models import (
    PropertyData,
    ValuationResult,
    RateLimitInfo,
    Address,
    ZoningInfo
)

# Dados tipados com Pydantic
resultado: PropertyData = client.consulta_endereco("Av Paulista", "1000")
print(f"SQL: {resultado.sql}")
print(f"Bairro: {resultado.bairro}")
print(f"Valor Venal: {resultado.valor_venal}")

Logging

import logging

# Habilitar logging de debug
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("iptuapi")

# Logs incluem:
# - Requisicoes enviadas
# - Respostas recebidas
# - Retries automaticos
# - Rate limit info

Testes

# Rodar testes
pytest

# Com coverage
pytest --cov=iptuapi

# Testes especificos
pytest tests/test_client.py -v

Cidades Suportadas

Codigo	Cidade
sp	Sao Paulo
rj	Rio de Janeiro
bh	Belo Horizonte
recife	Recife
curitiba	Curitiba
poa	Porto Alegre
salvador	Salvador
fortaleza	Fortaleza
campinas	Campinas
santos	Santos

Licenca

MIT License - veja LICENSE para detalhes.

Links

• Documentacao
• API Reference
• Portal do Desenvolvedor