Som Energia Open Data API (0.2.26)

Download OpenAPI specification:Download

License: GNU Affero General Public License

This API can be used to obtain metrics about Som Energia and several related visualizations and widgets.

Source metric measurements are obtained at the start of every first of month with city granularity. That is the smaller resolution this API provides: month and city. Coarser resolutions in time and space are obtained by aggregation of those source measurements.

Because the measurement for a day is obtained at the begining of that day, a value for 2020-01-01 will include events up to the end of 2019 but none from 2020. Likewise, a value for 2020-02-01 will include events up to the end of January but none about February.

Be aware that each metric has particular considerations about its meaning and reliability. They are included in the metric description, retrievable by means of the discovery API.

Glossary:

Metric: Something to be measured
Relative metric: Something available to relativize metrics (population, surface, existing supply points, overall energy consumption...)
Geolevel: A geographical partition: country, state, city...
Region: Each of the elements of the geolevel. For instance, at country geolevel we have as regions Spain, France...

About

Information about the running API

API version

Returns current and oldest backward compatible versions

query Parameters

format

string Nullable

Enum: "json" "yaml" null

Format for the result (yaml, json). yaml if not (properly) specified.

Responses

Response samples

200

Content type

{"version": "0.2.26",
"compat": "0.2.1"
}

API specification

API specification using OpenAPI 3.0 in YAML format.

Discovery

Discovering the evolving elements of the API: metrics, geolevels...

Available metrics

query Parameters

lang	string Nullable Enum: "ca" "gl" "eu" "es" "en" null Language to force for translated texts. If no language is forced, the one in the browser (Accepted-Language header) is taken. If the languange is not one of the supported ones, english is taken by default.
format	string Nullable Enum: "json" "yaml" null Format for the result (yaml, json). yaml if not (properly) specified.

Responses

Response samples

200

Content type

{
  "metrics": [
    {
      "id": "members",
      "text": "Members",
      "description": "Members of the cooperative at the end of the day."
    },
    {
      "id": "contracts",
      "text": "Contracts",
      "description": "Active contracts at the end of the day."
    }
  ]
}

Available geolevels

Returns the geolevels (short for geographical levels) that can be used in queries. For example, countries, cities...

query Parameters

lang	string Nullable Enum: "ca" "gl" "eu" "es" "en" null Language to force for translated texts. If no language is forced, the one in the browser (Accepted-Language header) is taken. If the languange is not one of the supported ones, english is taken by default.
format	string Nullable Enum: "json" "yaml" null Format for the result (yaml, json). yaml if not (properly) specified.

Responses

Response samples

200

Content type

{
  "geolevels": [
    {
      "id": "world",
      "text": "World",
      "mapable": false
    },
    {
      "id": "country",
      "text": "Country",
      "parent": "world",
      "plural": "countries",
      "mapable": false
    },
    {
      "id": "ccaa",
      "text": "Autonomous Community",
      "parent": "country",
      "plural": "ccaas"
    },
    {
      "id": "state",
      "text": "State",
      "parent": "ccaa",
      "plural": "states"
    },
    {
      "id": "city",
      "text": "City",
      "parent": "state",
      "plural": "cities",
      "mapable": false
    },
    {
      "id": "localgroup",
      "text": "Local Group",
      "parent": "world",
      "plural": "localgroups",
      "detailed": false,
      "mapable": false
    }
  ]
}

Available geolevels values

Returns the available values for a given geographical division.

path Parameters

geolevel

required

string[a-z][a-z0-9]+

Enum: "country" "ccaa" "state" "city" "localgroup"

Geographical detail level, including aliased geolevel alias, like localgroup.

query Parameters

city	Array of strings (CodeArray) INE codes of cities to be included
state	Array of strings (CodeArray) INE codes of states to be included
ccaa	Array of strings (CodeArray) INE codes of CCAAs to be included
country	Array of strings (CodeArray) ISO codes of countries to be included
localgroup	Array of strings (CodeArray) Codes of the local groups to be included
lang	string Nullable Enum: "ca" "gl" "eu" "es" "en" null Language to force for translated texts. If no language is forced, the one in the browser (Accepted-Language header) is taken. If the languange is not one of the supported ones, english is taken by default.
format	string Nullable Enum: "json" "yaml" null Format for the result (yaml, json). yaml if not (properly) specified.

Responses

Response samples

200

Content type

application/yaml

Example

All the CCAA's. Force name translation to Spanish instead of using the browser language.

{
  "options": {
    "10": "Comunidad Valenciana",
    "11": "Extremadura",
    "12": "Galicia",
    "13": "Madrid, Comunidad de",
    "14": "Murcia, Región de",
    "15": "Navarra, Comunidad Foral de",
    "16": "País Vasco",
    "17": "Rioja, La",
    "01": "Andalucia",
    "02": "Aragón",
    "03": "Asturias, Principado de",
    "04": "Baleares, Islas",
    "05": "Canarias",
    "06": "Cantabria",
    "07": "Castilla y León",
    "08": "Castilla - La Mancha",
    "09": "Cataluña"
  }
}

Numeric data

Obtaining processable numeric data

Metric data on a given date

Returns the metric computed with the given geographical level of detail on a given date.

Geographical fliters in the query string restrict the regions to be considered. Filters are additive, a city, the lowest level of detail, is incorporated if it matches any provided filter.

Elidible parts:

/by/{geolevel}: when omited means world
/on/{date}: when omitted means the latest available date

Some examples:

/contracts
- Current number of contracts:
/members/by/state
- Current members at every state:
/members/by/ccaa/on/2018-02-01
- Members at every CCAA on 2018-02-01:
/members/by/city?state=01&state=20
- Members by city on Araba and Gipuzcoa provinces:

path Parameters

metric required	string[a-z][a-z0-9]+ Enum: "contracts" "members" "selfconsumptioncontracts" "newcontracts" "newmembers" "newselfconsumptioncontracts" "canceledcontracts" "canceledmembers" "canceledselfconsumptioncontracts" The code of a supported metric (see /discover/metrics)
geolevel required	string Nullable [a-z][a-z0-9]+ Default: null Enum: "country" "ccaa" "state" "city" null Geographical level of detail. Use the golevel to get mor geographical detail (country, ccaa, state, city). For just the global numbers, remove the whole `/by/{geolevel}` portion of the path.
ondate required	string <date> Single date, in ISO format (YYYY-MM-DD). To obtain the last available data, remove the whole `/on/:onDate` portion of the path.

query Parameters

lang	string Nullable Enum: "ca" "gl" "eu" "es" "en" null Language to force for translated texts. If no language is forced, the one in the browser (Accepted-Language header) is taken. If the languange is not one of the supported ones, english is taken by default.
format	string Nullable Enum: "tsv" "yaml" "json" null Format for the result (yaml, json, tsv). yaml if not (properly) specified.
city	Array of strings (CodeArray) INE codes of cities to be included
state	Array of strings (CodeArray) INE codes of states to be included
ccaa	Array of strings (CodeArray) INE codes of CCAAs to be included
country	Array of strings (CodeArray) ISO codes of countries to be included
localgroup	Array of strings (CodeArray) Codes of the local groups to be included

Responses

Response samples

200

Content type

Members detailed by CCAA on 2013-01-01

{
  "dates": [
    "2013-01-01T00:00:00.000Z"
  ],
  "values": [
    3197
  ],
  "countries": {
    "ES": {
      "name": "España",
      "values": [
        3197
      ],
      "ccaas": {
        "10": {
          "name": "Comunidad Valenciana",
          "values": [
            224
          ]
        },
        "11": {
          "name": "Extremadura",
          "values": [
            14
          ]
        },
        "12": {
          "name": "Galicia",
          "values": [
            24
          ]
        },
        "13": {
          "name": "Madrid, Comunidad de",
          "values": [
            145
          ]
        },
        "14": {
          "name": "Murcia, Región de",
          "values": [
            11
          ]
        },
        "15": {
          "name": "Navarra, Comunidad Foral de",
          "values": [
            151
          ]
        },
        "16": {
          "name": "País Vasco",
          "values": [
            53
          ]
        },
        "17": {
          "name": "Rioja, La",
          "values": [
            37
          ]
        },
        "01": {
          "name": "Andalucia",
          "values": [
            48
          ]
        },
        "02": {
          "name": "Aragón",
          "values": [
            124
          ]
        },
        "03": {
          "name": "Asturias, Principado de",
          "values": [
            13
          ]
        },
        "04": {
          "name": "Baleares, Islas",
          "values": [
            235
          ]
        },
        "05": {
          "name": "Canarias",
          "values": [
            0
          ]
        },
        "06": {
          "name": "Cantabria",
          "values": [
            12
          ]
        },
        "08": {
          "name": "Castilla - La Mancha",
          "values": [
            28
          ]
        },
        "07": {
          "name": "Castilla y León",
          "values": [
            24
          ]
        },
        "09": {
          "name": "Cataluña",
          "values": [
            2054
          ]
        }
      }
    }
  }
}

Metric data on in a series of dates

Returns the metric computed with the given geographical level of detail for a series of dates.

Geographical fliters in the query string restrict the regions to be considered. Filters are additive, a city, the lowest level of detail, is incorporated if it matches any provided filter.

Use the filters in the query string to restrict to a group of geographical entities. The filters are additive. That means that any city matching any of the specified values will be counted.

Elidible parts:

/by/{geolevel}: when omited means world
/from/{date}: when omitted means the first available date
/to/{date}: when omitted means the latest available date

Some examples:

/contracts/yearly
- Evolution of all contracts every year
/members/monthly/from/2018-01-01/to/2019-01-01
- Monthly evolution of members during 2018
/members/by/city/yearly/from/2018-01-01?state=01&state=20
- Members by city on Araba (01) and Gipuzcoa (20) provinces every year since 2018

path Parameters

metric required	string[a-z][a-z0-9]+ Enum: "contracts" "members" "selfconsumptioncontracts" "newcontracts" "newmembers" "newselfconsumptioncontracts" "canceledcontracts" "canceledmembers" "canceledselfconsumptioncontracts" The code of a supported metric (see /discover/metrics)
geolevel required	string Nullable [a-z][a-z0-9]+ Default: null Enum: "country" "ccaa" "state" "city" null Geographical level of detail. Use the golevel to get mor geographical detail (country, ccaa, state, city). For just the global numbers, remove the whole `/by/{geolevel}` portion of the path.
frequency required	string Enum: "monthly" "yearly" Indicate a date sequence (only first day of the month, year...)
fromdate required	string <date> Earlier date to show, in iso format (YYYY-MM-DD). To set it to the first date available data, remove the whole `/from/{fromdate}` portion of the path.
todate required	string <date> Later date to show, in iso format (YYYY-MM-DD). To set it to the last date available data, remove the whole `/to/{todate}` portion of the path.

query Parameters

lang	string Nullable Enum: "ca" "gl" "eu" "es" "en" null Language to force for translated texts. If no language is forced, the one in the browser (Accepted-Language header) is taken. If the languange is not one of the supported ones, english is taken by default.
format	string Nullable Enum: "tsv" "yaml" "json" null Format for the result (yaml, json, tsv). yaml if not (properly) specified.
city	Array of strings (CodeArray) INE codes of cities to be included
state	Array of strings (CodeArray) INE codes of states to be included
ccaa	Array of strings (CodeArray) INE codes of CCAAs to be included
country	Array of strings (CodeArray) ISO codes of countries to be included
localgroup	Array of strings (CodeArray) Codes of the local groups to be included

Responses

Response samples

200

Content type

Members detailed by CCAA, evolution from 2010-01-01 2010-01-01 yearly

{
  "dates": [
    "2010-01-01T00:00:00.000Z",
    "2011-01-01T00:00:00.000Z",
    "2012-01-01T00:00:00.000Z",
    "2013-01-01T00:00:00.000Z"
  ],
  "values": [
    0,
    0,
    277,
    3197
  ],
  "countries": null,
  "ES": {
    "10": {
      "name": "Comunidad Valenciana",
      "values": [
        0,
        0,
        11,
        224
      ]
    },
    "11": {
      "name": "Extremadura",
      "values": [
        0,
        0,
        0,
        14
      ]
    },
    "12": {
      "name": "Galicia",
      "values": [
        0,
        0,
        0,
        24
      ]
    },
    "13": {
      "name": "Madrid, Comunidad de",
      "values": [
        0,
        0,
        3,
        145
      ]
    },
    "14": {
      "name": "Murcia, Región de",
      "values": [
        0,
        0,
        0,
        11
      ]
    },
    "15": {
      "name": "Navarra, Comunidad Foral de",
      "values": [
        0,
        0,
        6,
        151
      ]
    },
    "16": {
      "name": "País Vasco",
      "values": [
        0,
        0,
        0,
        53
      ]
    },
    "17": {
      "name": "Rioja, La",
      "values": [
        0,
        0,
        0,
        37
      ]
    },
    "name": "España",
    "values": [
      0,
      0,
      277,
      3197
    ],
    "ccaas": null,
    "01": {
      "name": "Andalucia",
      "values": [
        0,
        0,
        0,
        48
      ]
    },
    "02": {
      "name": "Aragón",
      "values": [
        0,
        0,
        0,
        124
      ]
    },
    "03": {
      "name": "Asturias, Principado de",
      "values": [
        0,
        0,
        0,
        13
      ]
    },
    "04": {
      "name": "Baleares, Islas",
      "values": [
        0,
        0,
        1,
        235
      ]
    },
    "05": {
      "name": "Canarias",
      "values": [
        0,
        0,
        0,
        0
      ]
    },
    "06": {
      "name": "Cantabria",
      "values": [
        0,
        0,
        0,
        12
      ]
    },
    "08": {
      "name": "Castilla - La Mancha",
      "values": [
        0,
        0,
        0,
        28
      ]
    },
    "07": {
      "name": "Castilla y León",
      "values": [
        0,
        0,
        0,
        24
      ]
    },
    "09": {
      "name": "Cataluña",
      "values": [
        0,
        0,
        256,
        2054
      ]
    }
  }
}

Maps

Generate geographical distribution maps for the metrics

Absolute metric map

Returns a map representing the geographical distribution of the metric on a given date.

Use the geolevel choose the map detail (ccaa, state).

Elidible parts:

/by/{geolevel}: when omited means ccaa (Not world!)
/on/{date}: when omitted means the latest available date

[Experimental] You can specify the extent of the map, by default country=ES. It will work if a map template for the combination of extent and geolevel exists.

Examples:

/map/contracts
- Current number of contracts by ccaa
/map/members/by/state
- Current members at every state
/map/members/by/ccaa/on/2018-02-01
- Members at every CCAA on 2018-02-01
/map/members/by/city?localgroup=BaixMontseny
- Current members at every city of Baix Montseny localgroup

path Parameters

metric required	string[a-z][a-z0-9]+ Enum: "contracts" "members" "selfconsumptioncontracts" "newcontracts" "newmembers" "newselfconsumptioncontracts" "canceledcontracts" "canceledmembers" "canceledselfconsumptioncontracts" The code of a supported metric (see /discover/metrics)
geolevel required	string[a-z][a-z0-9]+ Enum: "ccaa" "state" "city" Geographical level of detail. Use the golevel to get mor geographical detail (ccaa, state).
ondate required	string <date> Single date, in ISO format (YYYY-MM-DD). To obtain the last available data, remove the whole `/on/:onDate` portion of the path.

query Parameters

country	string (GeoCode) [a-zA-Z0-9]+ (Experimental) Set the extent of the map to the country This parameter is incompatible with other extent parameters. Available value `ES` (the default if no other extent is specified) with `state` or `ccaa` geolevels.
localgroup	string (GeoCode) [a-zA-Z0-9]+ (Experimental) Set the extent of the map to the local group. This parameter is incompatible with other extent parameters. Available values `BaixMontseny` and `BaixLlobregat` with `city` geolevel.
lang	string Nullable Enum: "ca" "gl" "eu" "es" "en" null Language to force for translated texts. If no language is forced, the one in the browser (Accepted-Language header) is taken. If the languange is not one of the supported ones, english is taken by default.

Responses

Relative metric map

Returns a map representing the geographical distribution at a given date of the metric relative to a reference metric (population).

Elidible parts:

/by/{geolevel}: when omited means ccaa (Not world!)
/from/{date}: when omitted means the first available date
/to/{date}: when omitted means the latest available date

[Experimental] You can specify the extent of the map, by default country=ES. It will work if a map template for the combination of extent and geolevel exists.

path Parameters

metric required	string[a-z][a-z0-9]+ Enum: "contracts" "members" "selfconsumptioncontracts" "newcontracts" "newmembers" "newselfconsumptioncontracts" "canceledcontracts" "canceledmembers" "canceledselfconsumptioncontracts" The code of a supported metric (see /discover/metrics)
relativemetric required	string[a-z][a-z0-9]+ Value: "population" One of the supported metrics to relativize main metrics. (By now just `population`)
geolevel required	string[a-z][a-z0-9]+ Enum: "ccaa" "state" "city" Geographical level of detail. Use the golevel to get mor geographical detail (ccaa, state).
ondate required	string <date> Single date, in ISO format (YYYY-MM-DD). To obtain the last available data, remove the whole `/on/:onDate` portion of the path.

query Parameters

country	string (GeoCode) [a-zA-Z0-9]+ (Experimental) Set the extent of the map to the country This parameter is incompatible with other extent parameters. Available value `ES` (the default if no other extent is specified) with `state` or `ccaa` geolevels.
localgroup	string (GeoCode) [a-zA-Z0-9]+ (Experimental) Set the extent of the map to the local group. This parameter is incompatible with other extent parameters. Available values `BaixMontseny` and `BaixLlobregat` with `city` geolevel.
lang	string Nullable Enum: "ca" "gl" "eu" "es" "en" null Language to force for translated texts. If no language is forced, the one in the browser (Accepted-Language header) is taken. If the languange is not one of the supported ones, english is taken by default.

Responses

Absolute metric map animation

Returns an animated map of the evolving geographical distribution for a serie of dates of the metric.

Use the geolevel choose the map detail (ccaa, state).

Elidible parts:

/by/{geolevel}: when omited means ccaa (Not world!)
/from/{date}: when omitted means the first available date
/to/{date}: when omitted means the latest available date

[Experimental] You can specify the extent of the map, by default country=ES. It will work if a map template for the combination of extent and geolevel exists.

path Parameters

metric required	string[a-z][a-z0-9]+ Enum: "contracts" "members" "selfconsumptioncontracts" "newcontracts" "newmembers" "newselfconsumptioncontracts" "canceledcontracts" "canceledmembers" "canceledselfconsumptioncontracts" The code of a supported metric (see /discover/metrics)
geolevel required	string[a-z][a-z0-9]+ Enum: "ccaa" "state" "city" Geographical level of detail. Use the golevel to get mor geographical detail (ccaa, state).
frequency required	string Enum: "monthly" "yearly" Indicate a date sequence (only first day of the month, year...)
fromdate required	string <date> Earlier date to show, in iso format (YYYY-MM-DD). To set it to the first date available data, remove the whole `/from/{fromdate}` portion of the path.
todate required	string <date> Later date to show, in iso format (YYYY-MM-DD). To set it to the last date available data, remove the whole `/to/{todate}` portion of the path.

query Parameters

country	string (GeoCode) [a-zA-Z0-9]+ (Experimental) Set the extent of the map to the country This parameter is incompatible with other extent parameters. Available value `ES` (the default if no other extent is specified) with `state` or `ccaa` geolevels.
localgroup	string (GeoCode) [a-zA-Z0-9]+ (Experimental) Set the extent of the map to the local group. This parameter is incompatible with other extent parameters. Available values `BaixMontseny` and `BaixLlobregat` with `city` geolevel.
lang	string Nullable Enum: "ca" "gl" "eu" "es" "en" null Language to force for translated texts. If no language is forced, the one in the browser (Accepted-Language header) is taken. If the languange is not one of the supported ones, english is taken by default.

Responses

Relative metric map animation

Returns an animated map of the evolving geographical distribution for a serie of dates of the metric relative to the reference metric.

Use the geolevel choose the map detail (ccaa, state).

Elidible parts:

/by/{geolevel}: when omited means ccaa (Not world!)
/from/{date}: when omitted means the first available date
/to/{date}: when omitted means the latest available date

[Experimental] You can specify the extent of the map, by default country=ES. It will work if a map template for the combination of extent and geolevel exists.

path Parameters

metric required	string[a-z][a-z0-9]+ Enum: "contracts" "members" "selfconsumptioncontracts" "newcontracts" "newmembers" "newselfconsumptioncontracts" "canceledcontracts" "canceledmembers" "canceledselfconsumptioncontracts" The code of a supported metric (see /discover/metrics)
relativemetric required	string[a-z][a-z0-9]+ Value: "population" One of the supported metrics to relativize main metrics. (By now just `population`)
geolevel required	string[a-z][a-z0-9]+ Enum: "ccaa" "state" "city" Geographical level of detail. Use the golevel to get mor geographical detail (ccaa, state).
frequency required	string Enum: "monthly" "yearly" Indicate a date sequence (only first day of the month, year...)
fromdate required	string <date> Earlier date to show, in iso format (YYYY-MM-DD). To set it to the first date available data, remove the whole `/from/{fromdate}` portion of the path.
todate required	string <date> Later date to show, in iso format (YYYY-MM-DD). To set it to the last date available data, remove the whole `/to/{todate}` portion of the path.

query Parameters

country	string (GeoCode) [a-zA-Z0-9]+ (Experimental) Set the extent of the map to the country This parameter is incompatible with other extent parameters. Available value `ES` (the default if no other extent is specified) with `state` or `ccaa` geolevels.
localgroup	string (GeoCode) [a-zA-Z0-9]+ (Experimental) Set the extent of the map to the local group. This parameter is incompatible with other extent parameters. Available values `BaixMontseny` and `BaixLlobregat` with `city` geolevel.
lang	string Nullable Enum: "ca" "gl" "eu" "es" "en" null Language to force for translated texts. If no language is forced, the one in the browser (Accepted-Language header) is taken. If the languange is not one of the supported ones, english is taken by default.