Skip to content

jfoclpf/geoapi.pt

main
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?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
res
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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

GEO API PT

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 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 file openapi.yaml 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/cp/2495-300)

Fetch JSON with Curl

Install NPM module json globally with npm i -g json

Now just run for example curl -s https://json.geoapi.pt/gps/38.748406,-9.102984 | json

$ curl -s https://json.geoapi.pt/gps/38.748406,-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 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 -- --port 8080

Debug

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