Dados do hexplace para o seu site ou aplicação

Dados de localidades de Portugal e Espanha, em breve de outros países: uma API JSON sem chave, widgets para incorporar e páginas simples para ferramentas de IA. Grátis, também para uso comercial, com crédito e uma ligação para o hexplace.

A API

JSON através de pedidos GET simples. Sem chave e sem registo; qualquer site a pode chamar a partir do navegador. Cada resposta inclui a sua licença e o crédito a mostrar.

Endereço	O que devolve
`/api/v1/`	Os países, as datas das suas versões e os endpoints
`/api/v1/portugal/towns`	Todas as localidades com os seus valores principais (clima, custos, acessos) e ligações
`/api/v1/portugal/towns/tavira`	Uma localidade: clima por mês, melhores meses, habitação, comércio e serviços, riscos, a quem convém
`/api/v1/portugal/towns/tavira/months/08`	Uma localidade num mês (01 a 12)
`/api/v1/portugal/rankings`	Os rankings
`/api/v1/portugal/rankings/warmest-winters`	Um ranking, top 100
`/api/v1/portugal/where/08`	As localidades mais quentes num mês
`/api/v1/openapi.json`	Esta API descrita em OpenAPI 3.1, para geradores de clientes e ferramentas de IA

Os dados são reconstruídos todas as semanas. Guarde as respostas em cache durante uma hora ou mais e limite-se a poucos pedidos por segundo.

Exemplo

const res = await fetch("https://hexplace.org/api/v1/portugal/towns/tavira");
const data = await res.json();
console.log(data.summary);
// mostrar o crédito que a licença pede:
document.querySelector("#credit").innerHTML = data.attribution.credit_html;

Cada valor indica o seu conjunto de dados e a sua precisão nos indicadores completos da localidade (data.json, também em CSV).

Todas as localidades de Portugal num só ficheiro: portugal/towns.csv. As colunas a seguir às da própria localidade são os ids de indicador da API; uma célula vazia significa que a localidade não tem um valor suficientemente preciso para publicar.

Widgets

Um cartão de localidade, um gráfico do clima ou um ranking, sempre atualizados. Escolha um no construtor de widgets e cole o código.

<iframe src="https://hexplace.org/embed/portugal/tavira/card/" width="340" height="300"
  style="border:0;max-width:100%" loading="lazy" title="Tavira pelo hexplace"></iframe>
<p><a href="https://hexplace.org/pt/portugal/tavira/">Tavira em números</a> pelo hexplace</p>

Abrir o construtor de widgets

Os editores que leem oEmbed (Ghost, Notion e outros) mostram o widget quando cola a ligação de uma localidade ou de um ranking. O endpoint é https://hexplace.org/oembed?url=….

Selos de ranking

Uma localidade no top 25 de um ranking, ou no top 10 da sua região, tem um selo para o seu site: uma imagem com ligação para o ranking, que mostra a posição atual.

Câmaras municipais, postos de turismo, hotéis e agências imobiliárias podem mostrar a posição da sua localidade. Os selos de cada localidade e o respetivo código estão na sua página de selos, por exemplo /pt/portugal/tavira/badges/.

Para ferramentas de IA

Cada página de localidade tem uma versão gémea em Markdown simples, com os seus factos, fontes e a forma de a citar.

/pt/portugal/tavira/index.md Tavira em Markdown
/llms.txt o que o hexplace cobre, para modelos de linguagem
/llms-full.txt todas as localidades com a sua página em Markdown

Licença e crédito

Os dados são publicados sob CC BY 4.0: use-os livremente, também para fins comerciais, desde que credite o hexplace com uma ligação para a página de onde vêm os dados, por exemplo Dados: hexplace (https://hexplace.org/portugal/tavira/). Os valores do OpenStreetMap continuam sob a ODbL. Cada conjunto de dados e a sua licença estão listados na metodologia.