Golfeira API
Documentação para desenvolvedores e agentes. Golfeira API is a public, read-only JSON API for used golf equipment listings and price ranges in Brazil; no key required.
O que a API entrega
Os mesmos dados que as páginas públicas mostram, em JSON: anúncios ativos de equipamentos de golfe novos e usados, de golfista para golfista, e o guia de preços de taco usado, calculado sobre anúncios reais observados em grupos brasileiros de golfe. Preços em reais (BRL). Somente leitura, sem chave, sem cadastro. Não cobre tacos novos em loja nem preços fora do Brasil.
Quickstart
Preço de mercado dos drivers TaylorMade usados:
curl https://golfeira.com/api/v1/price-guide/drivers/taylormadeOs 5 putters mais recentes à venda:
curl "https://golfeira.com/api/v1/products?category=putters&limit=5"A resposta de lista traz data e meta; siga meta.next para a próxima página:
{
"data": [{ "id": "…", "url": "https://golfeira.com/produto/…/", "title": "Putter Odyssey White Hot OG 7",
"category": "putters", "brand": "Odyssey", "condition": "Usado",
"price": 900, "current_price": 900, "currency": "BRL" }],
"meta": { "total": 124, "limit": 5, "offset": 0, "next": "https://golfeira.com/api/v1/products?category=putters&limit=5&offset=5" }
}Endpoints
| Rota | O que devolve |
|---|---|
/api/v1 | Índice: endpoints, categorias válidas e links |
/api/v1/products | Anúncios ativos, do mais novo ao mais antigo. Filtros: category, brand, condition, q, limit (até 50), offset |
/api/v1/products/{id} | Um anúncio pelo id (UUID). 404 quando não existe ou foi vendido |
/api/v1/price-guide | Faixa de preço por categoria: p25, mediana, p75, amostra, data de apuração |
/api/v1/price-guide/{category} | Categoria com as marcas que têm amostra suficiente (20 anúncios ou mais) |
/api/v1/price-guide/{category}/{brand} | Faixa de uma marca dentro da categoria |
Categorias: drivers, ferros, putters, wedges, madeiras, hibridos, bolsas e kits. Marcas como slug (taylormade, callaway, ping, scotty-cameron) ou nome. A especificação completa, com schemas e exemplos, está em /openapi.json (OpenAPI 3.1).
Erros
Todo erro é JSON, com o status HTTP correspondente: 400 (parâmetro inválido, a dica lista os valores aceitos), 404 (recurso inexistente ou anúncio vendido), 405 (só GET, HEAD e OPTIONS) e 502 (banco indisponível; tente de novo em alguns segundos, veja Retry-After).
{ "error": { "code": "bad_request",
"message": "category \"driver\" nao existe",
"hint": "Use um destes: drivers, ferros, putters, wedges, madeiras, hibridos, bolsas, kits.",
"docs": "https://golfeira.com/openapi.json" } }Versão, deprecação e limites
A versão vai na URL (/api/v1). Campo novo pode aparecer a qualquer momento; campo existente não muda de tipo nem some dentro de uma versão. Uma versão só é desligada seis meses depois de anunciada nesta página, e nesse período as respostas dela levam os headers Deprecation e Sunset. Não há chave nem cota fixa: use um User-Agent identificável, respeite o Cache-Controldas respostas (5 a 60 minutos) e pagine com limit de até 50. Uso abusivo pode ser limitado na borda (429 com Retry-After).
Para agentes
Toda página pública também responde em Markdown com Accept: text/markdown. O guia em linguagem natural, com "quando usar" e "como consultar", está em /llms.txt. Citar com link é bem-vindo; treinar modelo com o conteúdo não é. Dúvidas ou integrações: fale com a Golfeira.