geoptapi

    1.0.2 • Public • Published

    GEO PT API

    Provides information on official divisional administrative regions of Portugal (based on "Carta Administrativa Oficial de Portugal, 2020", from here). It includes information on mainland Portugal, Azores and Madeira.

    You can use freely the public API at geoptapi.org.

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

    Paths and parameters

    /gps

    The /gps path has three parameters: lat, lon and detalhes (optional).

    The GET request /gps?lat=40.153687&lon=-8.514602 returns a JSON

    {
       "freguesia":"Anobra",
       "concelho":"Condeixa-A-Nova",
       "distrito":"Coimbra"
    }

    You may also request details for the returned municipality and parish with
    /gps?lat=40.153687&lon=-8.514602&detalhes=1, which outputs:

    {
       "freguesia":"Anobra",
       "concelho":"Condeixa-A-Nova",
       "distrito":"Coimbra",
       "detalhesFreguesia":{
          "codigo":"6946",
          "nome":"Anobra",
          "municipio": "CONDEIXA-A-NOVA",
          "nif":"501280049",
          "rua":"Beco da Junta",
          "localidade":"Anobra (CONDEIXA-A-NOVA)",
          "codigopostal":"3150-012",
          "descrpostal":"ANOBRA",
          "email":"jfanobra@gmail.com",
          "telefone":"239943911",
          "fax":"239943911",
          "sitio":"www.freguesiadeanobra.pt",
          "codigoine":"60401",
          "eleitores2011":"1023",
          "populacao2011":"1357",
          "areaha":"1638.29",
          "nomecompleto":"Anobra"
       },
       "detalhesMunicipio":{
          "codigo":"2630",
          "nome":"CONDEIXA-A-NOVA",
          "nif":"501275380",
          "rua":"Largo Artur Barreto",
          "localidade":"CONDEIXA-A-NOVA",
          "codigopostal":"3150-128",
          "descrpostal":"CONDEIXA-A-NOVA",
          "email":"geral@cm-condeixa.pt",
          "telefone":"239949120",
          "fax":"239942711",
          "sitio":"www.cm-condeixa.pt",
          "presidentecamara":"Nuno Moita da Costa",
          "areaha":"138.67",
          "populacao":"17078",
          "eleitores":"12658",
          "codigoine":"604"
       }
    }

    /municipio or /municipios

    With no parameters, returns a JSON array with municipalities names, alphabetically sorted.

    Accept parameters nome, codigo, nif, codigopostal, email, telefone, fax, sitio and codigoine.

    For example the request /municipio?nome=Évora will return:

    {
      "codigo":"2643",
      "nif":"504828576",
      "rua":"Praça do Sertório",
      "localidade":"EVORA",
      "codigopostal":"7004-506",
      "descrpostal":"EVORA",
      "email":"cmevora@mail.evora.net",
      "telefone":"266777000",
      "fax":"266702950",
      "sitio":"www.cm-evora.pt",
      "presidentecamara":"Carlos Manuel Rodrigues Pinto de Sá",
      "areaha":"1307.03",
      "populacao":"56596",
      "eleitores":"47923",
      "codigoine":"705",
      "nome":"ÉVORA"
    }

    /freguesia or /freguesias

    With no parameters, returns a JSON array with parishes (freguesias) names, alphabetically sorted.

    Accept parameter nome, which makes reference to fields nome, nomecompleto and nomecompleto2. Also accepts parameters municipio, codigo, nif, codigopostal, email, telefone, fax, sitio and codigoine.

    For example the request /freguesia?nome=serzedelo will return

    [
       {
          "codigo":"6235",
          "nif":"506863115",
          "rua":"Rua do Grupo Desportivo, N.º 23",
          "localidade":"Serzedelo (GUIMARÃES)",
          "codigopostal":"4765-533",
          "descrpostal":"SERZEDELO",
          "email":"junta.serzedelo@gmail.com",
          "telefone":"253532236",
          "fax":"253532236",
          "sitio":"",
          "codigoine":"30866",
          "eleitores2011":"3504",
          "populacao2011":"4073",
          "areaha":"514.44",
          "nomecompleto":"Serzedelo",
          "nome":"Serzedelo",
          "municipio":"GUIMARÃES",
          "nomecompleto2":"Serzedelo"
       },
       {
          "codigo":"6269",
          "nif":"507009460",
          "rua":"Rua da Igreja",
          "localidade":"Serzedelo (PÓVOA DE LANHOSO)",
          "codigopostal":"4830-698",
          "descrpostal":"SERZEDELO",
          "email":"info@jf-serzedelo.pt",
          "telefone":"253636601",
          "fax":"253636601",
          "sitio":"",
          "codigoine":"30924",
          "eleitores2011":"798",
          "populacao2011":"830",
          "areaha":"964.51",
          "nomecompleto":"Serzedelo",
          "nome":"Serzedelo",
          "municipio":"PÓVOA DE LANHOSO",
          "nomecompleto2":"Serzedelo"
       }
    ]

    And the request /freguesia?nome=serzedelo&municipio=guimarães will return

    {
      "codigo":"6235",
      "nif":"506863115",
      "rua":"Rua do Grupo Desportivo, N.º 23",
      "localidade":"Serzedelo (GUIMARÃES)",
      "codigopostal":"4765-533",
      "descrpostal":"SERZEDELO",
      "email":"junta.serzedelo@gmail.com",
      "telefone":"253532236",
      "fax":"253532236",
      "sitio":"",
      "codigoine":"30866",
      "eleitores2011":"3504",
      "populacao2011":"4073",
      "areaha":"514.44",
      "nomecompleto":"Serzedelo",
      "nome":"Serzedelo",
      "municipio":"GUIMARÃES",
      "nomecompleto2":"Serzedelo"
    }

    /municipios/freguesias

    Returns a JSON array of objects, each object corresponding to a municipality and an array of its parishes

    [
       {
          "nome":"Abrantes",
          "freguesias":[
             "Bemposta",
             "Carvalhal",
             "Fontes",
             "Martinchel",
             "Mouriscas",
             "Pego",
             "Rio de Moinhos",
             "Tramagal",
             "União das freguesias de Abrantes (São Vicente e São João) e Alferrarede",
             "União das freguesias de Aldeia do Mato e Souto",
             "União das freguesias de Alvega e Concavada",
             "União das freguesias de São Facundo e Vale das Mós",
             "União das freguesias de São Miguel do Rio Torto e Rossio ao Sul do Tejo"
          ]
       },
       {
          "nome":"Aguiar da Beira",
          "freguesias":[
             "Carapito",
             "Cortiçada",
             "Dornelas",
             "Eirado",
             "Forninhos",
             "Pena Verde",
             "Pinheiro",
             "União das freguesias de Aguiar da Beira e Coruche",
             "União das freguesias de Sequeiros e Gradiz",
             "União das freguesias de Souto de Aguiar da Beira e Valverde"
          ]
       },
       "etc"
     ]

    How to install this API on your machine

    1. Install nodeJS, npm and git
    2. Clone the project:
      git clone https://github.com/jfoclpf/geoptapi.git
    3. Enter the newly created directory and install dependencies
      cd geoptapi && npm install
    4. Start the server
      npm start --port=8080

    Continuous operation

    For permanent and continuous operation use for example pm2 or forever, using directly the node script located at the root directory

    node server.js --port=8080.

    With pm2

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

    Debug

    DEBUG=http npm start --port=8080
    

    Keywords

    Install

    npm i geoptapi

    DownloadsWeekly Downloads

    5

    Version

    1.0.2

    License

    GPL-3.0-or-later

    Unpacked Size

    42 MB

    Total Files

    17

    Last publish

    Collaborators

    • jfolpf