Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

JSON API documentation Test API server CodeQL Security Check js-standard-style Request last hour Request last day
Donate with librepay Donate with librepay


RESTful API which provides information on official divisional administrative regions of Portugal (based on "Carta Administrativa Oficial de Portugal, 2021", from here). It includes information on mainland Portugal, Azores and Madeira. It also provides information on Postal Codes and Census. For more information see the resource and routines documentations.

You can use freely the public API at The limit per IP is 900 requests per 15 minutes (average of 1/sec).

It uses NodeJS (much faster than Python) to create a HTTP server allowing several GET requests. It pre-processes all the raw data for fast real-time delivery.

Docs and Routes

All the API documentation is at

This API follows the OpenAPI Specification, thus you can see all the routes in the file openapi.yaml file.


By default the server replies with text/html format. To receive JSON format, chose one of these:

  • add the query GET parameter json=1 to the URL (ex.: /municipio/évora?json=1);
  • set the HTTP request header Accept as JSON, that is, Accept: application/json; or
  • in case you're using the public API, use the host (ex:

Fetch JSON with Curl

Install NPM module json globally with npm i -g json

Now just run for example curl -s,-9.102984 | json

$ curl -s,-9.102984 | json
  "distrito": "Lisboa",
  "concelho": "Lisboa",
  "freguesia": "Marvila",
  "Secção Estatística (INE, BGRI 2021)": "011",
  "Subsecção Estatística (INE, BGRI 2021)": "06",
  "rua": "R Fernando Maurício",
  "n_porta": "30",
  "uso": "Tecido edificado contínuo predominantemente vertical",
  "altitude_m": 71,
  "CP": "1950-449",
  "descr_postal": "Lisboa"

Install this API on your machine

Tested on Linux, Windows and MacOS

  1. Install NodeJS and git
  2. Clone the project (just the latest version):
    git clone --depth=1
  3. Enter the newly created directory and install dependencies
    cd; npm ci
  4. Start the server
    npm start -- --port=8080

For more information run npm start -- --help

Continuous operation

For permanent and continuous operation (production) use for example pm2 or forever.

With pm2

npm install pm2@latest -g
pm2 start src/server/index.js -- --port 8080


DEBUG=geoapipt:* npm start -- --port=8080