jfoclpf / geoapi.pt

GEO API PT - Provides information for Portugal on official divisional administrative regions, georeferencing, census and postal codes

RESTful API which provides information on official divisional administrative regions of Portugal (based on "Carta Administrativa Oficial de Portugal, 2022", 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 https://geoapi.pt. 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 docs.geoapi.pt.

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

Resources and Routines

• To know more about the raw resources used by this API, see the res/ readme file
• To check available backend routines (for example to update raw resources) run npm run. Read more on the routines/ readme file

JSON or HTML

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 json.geoapi.pt (ex: json.geoapi.pt/codigo_postal/2495-300)

For pretty-printing JSON as HTML response, use in the query ?json=belo, for example /codigo_postal/2495-300?json=belo

Install this API on your machine

Option 1 (with docker)

Just run

docker run -p 8080:8080 jfoclpf/geoapi.pt:latest

or to run as a service in the background

docker run -p 8080:8080 -d jfoclpf/geoapi.pt:latest

Option 2 (directly with NodeJS)

Tested on Linux, Windows and MacOS

1. Install NodeJS and git
2. Clone the project (just the latest version):
   git clone --depth=1 https://github.com/jfoclpf/geoapi.pt.git
3. Enter the newly created directory and install dependencies
   cd geoapi.pt; 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 -- --buildFeAssets --port 8080

Debug

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