locations

Data source

Locations in the API are sourced from the GeoJSON datasets available in our datasets GitHub repository. The API provides only the properties of the GeoJSON features, excluding the geometries. This approach ensures practical response sizes, as including geometries would significantly increase the data payload. For now, if you need access to the geometries, you can download the full GeoJSON files from the repository. We are actively exploring ways to include geometries in the API in a scalable and efficient manner.

Available locations

The API provides the following locations in JSON format:

Districts

Districts are the top level division in the API and are identified by their DICOFRE code, a standardized identifier for geographic areas.

curl -X GET "https://api.carrismetropolitana.pt/v2/locations/districts"

{
  "data": [
    {
      "id": "01",
      "name": "District 01"
    }
  ],
  "status": "success",
  "timestamp": 0
}

Municipalities

Municipalities are subdivisions within a district and are identified by their DICOFRE code. Every geographical data point in the API is associated with at least one municipality, making it the “primary key” for location types.

curl -X GET "https://api.carrismetropolitana.pt/v2/locations/municipalities"

{
  "data": [
    {
      "district_id": "01",
      "id": "0101",
      "name": "Municipality 0101"
    }
  ],
  "status": "success",
  "timestamp": 0
}

Parishes

Parishes, known as “freguesias,” are optional administrative divisions within municipalities. They are identified by their DICOFRE code. Currently, only a limited number of objects in the API are associated with this location type. Expanding the use of parishes to enhance geographic precision is planned for future updates.

curl -X GET "https://api.carrismetropolitana.pt/v2/locations/parishes"

{
  "data": [
    {
      "district_id": "01",
      "id": "010101",
      "municipality_id": "0101",
      "name": "Parish 01"
    }
  ],
  "status": "success",
  "timestamp": 0
}

Localities

Localities are informal places known to local populations. We use this to diferentiate the location of similarly named objects. Objects may not have localities.

curl -X GET "https://api.carrismetropolitana.pt/v2/locations/localities"

null