geolocation

v1.0.0 Produção Em manutenção 
API oficial de geolocalização de Angola com dados atualizados (2025). 22 províncias, 326 municípios.


https://joaotomas.elprimesolution.com/api/gateway/geolocation Autenticação: API Key

Endpoints Disponíveis

GET
/status 
Verifica o status da API de geolocalização


GET
/provinces

Lista todas as 22 províncias de Angola com seus dados

GET
/provinces/{slug} 
Busca uma província específica pelo slug (ex: luanda, benguela)


GET
/municipalities 
Lista todos os municípios de Angola


GET
/municipalities/{provinceSlug?} 
Lista todos os municípios ou filtra por província (ex: /municipalities/luanda)


GET
/search 
Busca por províncias ou municípios usando o parâmetro q (ex: ?q=Luanda)


Documentação Completa

Introdução Ordem: 1 Publicado

Introdução à API de Geolocalização Angola

API de Geolocalização Angola



<p>Bem-vindo à API oficial de geolocalização de Angola! Esta API fornece dados completos e atualizados sobre as divisões administrativas do país.</p>

Dados Disponíveis


<ul>
    <li><strong>22 Províncias</strong> - Com dados de população, área, capital e região</li>
    <li><strong>326 Municípios</strong> - Distribuídos por todas as províncias</li>
    <li><strong>Dados atualizados</strong> - Baseados na nova divisão administrativa de 2025</li>
</ul>

Funcionalidades


<ul>
    <li>Listar todas as províncias com seus dados</li>
    <li>Buscar província por slug (ex: luanda, benguela)</li>
    <li>Listar municípios de uma província específica</li>
    <li>Busca por termo em províncias e municípios</li>
    <li>Cache integrado para respostas rápidas</li>
</ul>

Casos de Uso


<ul>
    <li>Sistemas de cadastro e validação de endereços</li>
    <li>Aplicações de e-commerce e delivery</li>
    <li>Dashboards e relatórios geográficos</li>
    <li>Integração com sistemas de CRM e ERP</li>
</ul>

URL Base


<pre><code>https://joaotomas.elprimesolution.com/api/geolocation</code></pre>
Autenticação Ordem: 2 Publicado

Autenticação e Chaves de API

Autenticação



Como obter uma chave de API


<p>Para utilizar a API de Geolocalização Angola, você precisa de uma chave de API válida. Siga os passos abaixo:</p>

Passo 1: Solicitar chave


<p>Entre em contacto através do <a href="/contacto" style="color: var(--accent);">formulário de contacto</a> para solicitar sua chave de API.</p>

Passo 2: Receber chave


<p>Você receberá uma chave no formato:</p>
<pre><code>pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx</code></pre>

Passo 3: Utilizar chave


<p>A chave deve ser enviada em todas as requisições no header:</p>
<pre><code>X-API-Key: sua-chave-aqui</code></pre>

Exemplo de requisição autenticada


<pre><code>curl -X GET "https://joaotomas.elprimesolution.com/api/geolocation/provinces" \
  -H "X-API-Key: pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"</code></pre>

Códigos de erro de autenticação


<table>
    <thead>
        <tr>
            <th>Código</th>
            <th>Descrição</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>401</td>
            <td>Chave de API inválida ou não fornecida</td>
        </tr>
        <tr>
            <td>403</td>
            <td>Permissão negada</td>
        </tr>
        <tr>
            <td>429</td>
            <td>Muitas requisições (rate limit excedido)</td>
        </tr>
    </tbody>
</table>
Endpoints Ordem: 3 Publicado

Endpoints da API de Geolocalização

Endpoints Disponíveis



1. Status da API


Endpoint


<pre><code>GET /status</code></pre>

Exemplo de requisição


<pre><code>curl https://joaotomas.elprimesolution.com/api/geolocation/status</code></pre>

Resposta


<pre><code>{
  "success": true,
  "status": "online",
  "data": {
    "status": "operacional",
    "timestamp": "2026-06-19T12:44:17.664Z",
    "version": "1.0.0",
    "service": "Geolocalização Angola API"
  }
}</code></pre>

<hr>

2. Listar Províncias


Endpoint


<pre><code>GET /provinces</code></pre>

Exemplo de requisição


<pre><code>curl https://joaotomas.elprimesolution.com/api/geolocation/provinces</code></pre>

Resposta


<pre><code>{
  "success": true,
  "total": 22,
  "data": [
    {
      "id": 1,
      "nome": "Luanda",
      "slug": "luanda",
      "capital": "Luanda",
      "codigo": "01",
      "regiao": "Norte",
      "populacao": 8333000,
      "area": 2418,
      "municipios": [...],
      "total_municipios": 9
    }
  ]
}</code></pre>

<hr>

3. Buscar Província por Slug


Endpoint


<pre><code>GET /provinces/{slug}</code></pre>

Parâmetros


<table>
    <thead>
        <tr>
            <th>Parâmetro</th>
            <th>Tipo</th>
            <th>Obrigatório</th>
            <th>Descrição</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>slug</td>
            <td>string</td>
            <td>Sim</td>
            <td>Slug da província (ex: luanda, benguela)</td>
        </tr>
    </tbody>
</table>

Exemplo de requisição


<pre><code>curl https://joaotomas.elprimesolution.com/api/geolocation/provinces/luanda</code></pre>

Resposta


<pre><code>{
  "success": true,
  "data": {
    "id": 1,
    "nome": "Luanda",
    "slug": "luanda",
    "capital": "Luanda",
    "codigo": "01",
    "regiao": "Norte",
    "populacao": 8333000,
    "area": 2418,
    "municipios": [...]
  }
}</code></pre>

<hr>

4. Listar Municípios


Endpoint


<pre><code>GET /municipalities/{provinceSlug?}</code></pre>

Parâmetros


<table>
    <thead>
        <tr>
            <th>Parâmetro</th>
            <th>Tipo</th>
            <th>Obrigatório</th>
            <th>Descrição</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>provinceSlug</td>
            <td>string</td>
            <td>Não</td>
            <td>Slug da província (opcional)</td>
        </tr>
    </tbody>
</table>

Exemplo 1: Todos os municípios


<pre><code>curl https://joaotomas.elprimesolution.com/api/geolocation/municipalities</code></pre>

Exemplo 2: Municípios de Luanda


<pre><code>curl https://joaotomas.elprimesolution.com/api/geolocation/municipalities/luanda</code></pre>

Resposta (Municípios de Luanda)


<pre><code>{
  "success": true,
  "provincia": "Luanda",
  "total": 9,
  "data": [
    {"nome": "Luanda", "slug": "luanda"},
    {"nome": "Belas", "slug": "belas"},
    {"nome": "Cazenga", "slug": "cazenga"},
    {"nome": "Viana", "slug": "viana"},
    {"nome": "Cacuaco", "slug": "cacuaco"},
    {"nome": "Quilamba Quiaxi", "slug": "quilamba-quiaxi"},
    {"nome": "Talatona", "slug": "talatona"},
    {"nome": "Samba", "slug": "samba"},
    {"nome": "Maianga", "slug": "maianga"}
  ]
}</code></pre>

<hr>

5. Buscar


Endpoint


<pre><code>GET /search?q={termo}</code></pre>

Parâmetros


<table>
    <thead>
        <tr>
            <th>Parâmetro</th>
            <th>Tipo</th>
            <th>Obrigatório</th>
            <th>Descrição</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>q</td>
            <td>string</td>
            <td>Sim</td>
            <td>Termo de busca</td>
        </tr>
    </tbody>
</table>

Exemplo de requisição


<pre><code>curl "https://joaotomas.elprimesolution.com/api/geolocation/search?q=Luanda"</code></pre>

Resposta


<pre><code>{
  "success": true,
  "resultados": {
    "provincias": [
      {
        "id": 1,
        "nome": "Luanda",
        "slug": "luanda",
        "capital": "Luanda",
        "regiao": "Norte"
      }
    ],
    "municipios": [
      {
        "nome": "Luanda",
        "slug": "luanda",
        "provincia": "Luanda",
        "provincia_slug": "luanda"
      }
    ]
  }
}</code></pre>
Exemplos Ordem: 4 Publicado

Exemplos Práticos de Uso

Exemplos Práticos



Exemplo em PHP


<pre><code>&lt;?php

function consultarProvincias($apiKey) {
    $ch = curl_init('https://joaotomas.elprimesolution.com/api/geolocation/provinces');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-Key: ' . $apiKey,
        'Accept: application/json'
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Uso
$apiKey = 'pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx';
$data = consultarProvincias($apiKey);

foreach ($data['data'] as $provincia) {
    echo $provincia['nome'] . ' - ' . $provincia['capital'] . "\n";
}
</code></pre>

Exemplo em JavaScript (Node.js)


<pre><code>const axios = require('axios');

async function getMunicipios(provinceSlug, apiKey) {
    try {
        const response = await axios.get(
            `https://joaotomas.elprimesolution.com/api/geolocation/municipalities/${provinceSlug}`,
            {
                headers: {
                    'X-API-Key': apiKey,
                    'Accept': 'application/json'
                }
            }
        );
        return response.data;
    } catch (error) {
        console.error('Erro:', error.message);
        return null;
    }
}

// Uso
const apiKey = 'pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx';
const dados = await getMunicipios('luanda', apiKey);

console.log(`Província: ${dados.provincia}`);
console.log(`Municípios: ${dados.total}`);
dados.data.forEach(m => console.log(`- ${m.nome}`));
</code></pre>

Exemplo em JavaScript (Frontend)


<pre><code>async function buscarProvincias(apiKey) {
    try {
        const response = await fetch(
            'https://joaotomas.elprimesolution.com/api/geolocation/provinces',
            {
                headers: {
                    'X-API-Key': apiKey,
                    'Accept': 'application/json'
                }
            }
        );
        return await response.json();
    } catch (error) {
        console.error('Erro:', error);
        return null;
    }
}

// Uso
const apiKey = 'pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx';
const data = await buscarProvincias(apiKey);

if (data.success) {
    const select = document.getElementById('provincias');
    data.data.forEach(p => {
        const option = document.createElement('option');
        option.value = p.slug;
        option.textContent = p.nome;
        select.appendChild(option);
    });
}
</code></pre>

Exemplo em Python


<pre><code>import requests

def buscar_provincias(api_key):
    headers = {
        'X-API-Key': api_key,
        'Accept': 'application/json'
    }
    
    response = requests.get(
        'https://joaotomas.elprimesolution.com/api/geolocation/provinces',
        headers=headers
    )
    
    return response.json()

# Uso
api_key = 'pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx'
data = buscar_provincias(api_key)

for provincia in data['data']:
    print(f"{provincia['nome']} - {provincia['capital']}")
</code></pre>
Erros Ordem: 5 Publicado

Erros Comuns e FAQ

Erros Comuns e FAQ



Códigos de Erro


<table>
    <thead>
        <tr>
            <th>Código</th>
            <th>Descrição</th>
            <th>Solução</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>200</td>
            <td>Sucesso</td>
            <td>-</td>
        </tr>
        <tr>
            <td>400</td>
            <td>Requisição inválida</td>
            <td>Verifique os parâmetros enviados</td>
        </tr>
        <tr>
            <td>401</td>
            <td>Não autorizado</td>
            <td>Verifique sua chave de API</td>
        </tr>
        <tr>
            <td>403</td>
            <td>Permissão negada</td>
            <td>Sua chave não tem permissão para este recurso</td>
        </tr>
        <tr>
            <td>404</td>
            <td>Recurso não encontrado</td>
            <td>Verifique o slug da província</td>
        </tr>
        <tr>
            <td>429</td>
            <td>Muitas requisições</td>
            <td>Aguarde e tente novamente</td>
        </tr>
        <tr>
            <td>500</td>
            <td>Erro interno</td>
            <td>Contacte o suporte</td>
        </tr>
    </tbody>
</table>

FAQ



1. Como obtenho uma chave de API?


<p>Entre em contacto através do <a href="/contacto" style="color: var(--accent);">formulário de contacto</a> no site.</p>

2. Qual é o limite de requisições?


<p>O limite padrão é de 100 requisições por minuto.</p>

3. Os dados são cacheados?


<p>Sim, as respostas são cacheadas por 1 hora para melhor performance.</p>

4. Quantas províncias existem em Angola?


<p>Atualmente, Angola tem 22 províncias com a nova divisão administrativa de 2025.</p>

5. Quantos municípios existem em Angola?


<p>Angola tem 326 municípios distribuídos pelas 22 províncias.</p>

6. Quais são as novas províncias?


<p>As novas províncias são: Ícolo e Bengo, Cuando, Cubango e Moxico Leste.</p>

7. A API é gratuita?


<p>Contacte para informações sobre planos e preços.</p>

Contacto


<p>Para suporte ou dúvidas: <a href="/contacto" style="color: var(--accent);">Formulário de Contacto</a></p>

Como consumir esta API

1.

Solicite sua chave de API

Entre em contacto através do formulário para obter acesso

2.

Faça requisições para o gateway

curl -X GET "https://joaotomas.elprimesolution.com/api/gateway/geolocation//status" \
  -H "X-API-Key: sua-chave-aqui" \
  -H "Accept: application/json"

Base URL: https://joaotomas.elprimesolution.com/api/gateway/geolocation

3.

Integre no seu projeto

Utilize os dados retornados na sua aplicação

Exemplo de Resposta

{
    "error": false,
    "name": "Lisboa Da Costa Coelho",
    "endereco": "SAMBA, NA, BAIRRO MUNDIAL-BENFICA",
    "data_de_nascimento": "1991-07-31"
}
Solicitar Chave de API Ver todas as APIs

API desenvolvida e mantida por João Nicolau Remos Tomás

© 2026 Todos os direitos reservados

geolocation | APIs João Tomás