Best Practice Library API Reference V1

Overview

The best practice library allows you to access the best practice examples published in the EEA Management Tool.

Authentication

Basic authorization via authorization header containing username and password is used for authentication. No session will ever be saved, so username and password have to be provided in every single request.

Basic Authorization

Basic authorization must include a base64 encoded string containing username and password, separated by a colon like: 'user:password'.

Get API Access

If you need access to the API, please contact eea@wienfluss.net.

Resources

There are five differnt types of resources you can query. (1) Branches, (2) Best Practice Examples, (3) Translations, (4) Images and (5) Files. Best Practice Example can be considered as a container for translations. As the API provides read-only access only GET requests are allowed. All responses are JSON responses. Error responses contain an error key (see section Error Codes).

Branch

The branch structure reflects countries, states or regions. To query a list of available branches see following sample requests.

Sample request: query all branches

This is the description
GET https://bpl.api.tool.european-energy-award.org/v1/branches/
Response:
['/', '/at/', '/at/burgenland/', '/at/krnten/', '/at/niedersterreich/', '/at/obersterreich/', '/at/salzburg/', '/at/steiermark/', '/at/tirol/', '/at/vorarlberg/', '/be/', '/be/vlaanderen/', '/be/wallonie/']

Sample request: query branches filtered by country

This is the description
GET https://bpl.api.tool.european-energy-award.org/v1/branches/at/
Response:
['/at/', '/at/burgenland/', '/at/krnten/', '/at/niedersterreich/', '/at/obersterreich/', '/at/salzburg/', '/at/steiermark/', '/at/tirol/', '/at/vorarlberg/']

Best Practice Examples

A Best Practice Example (BPE) is a container for potential multiple unique example translations. It provides information about available translations, and the example's origin language title. Language abbreviation does not include country code, but only two character language code. BPEs can be filtered by branch and language (see following sample requests). Response is orderd by the BPE key.

Sample request: query all examples

Basic query to retrieve all available best practice examples. Most likely you want to apply a filter instead of retrieving all examples, as shown in the following sample requests.
GET https://bpl.api.tool.european-energy-award.org/v1/
Response:
{'1312247': {'available_translations': {'de': 1312248}, 'id': 1312247, 'title': 'a'}, '1314452': {'available_translations': {'de': 1314453}, 'id': 1314452, 'title': 'Erneuerbare Wärmeerzeugung'}, '1314454': {'available_translations': {'de': 1314455}, 'id': 1314454, 'title': 'Smart City Strategie'}}
Attribute description:
available_translations
Dictionary of two char language abbreviation as key and translation ID value
Type: Dictionary
Keys: ['be', 'de', 'el', 'fr', 'hr', 'it', 'po', 'ro', 'uk']
title
Title of the best practice example in its original (first selected) language
Type: String (unicode)
id
ID of the example.
Type: Integer

Sample request: query all examples filtered by country

Query all examples in Vorarlberg, Austria. Branch filter is applied by simply appending the branch path.
GET https://bpl.api.tool.european-energy-award.org/v1/at/vorarlberg
Response:
{'1314456': {'available_translations': {'de': 1314457}, 'id': 1314456, 'title': 'LED-Tubes in Tiefgaragen'}, '1314458': {'available_translations': {'de': 1314459}, 'id': 1314458, 'title': 'Gelebte Kooperation in Dornbirn'}}
Attribute description:

Sample request: query all examples filtered by country and language

Query all examples in Vorarlberg, Austria in German. Language filter is applied by using the 'lang' keyword.
GET https://bpl.api.tool.european-energy-award.org/v1/at/vorarlberg/lang/de
Response:
{'1314456': {'available_translations': {'de': 1314457}, 'id': 1314456, 'title': 'LED-Tubes in Tiefgaragen'}, '1314458': {'available_translations': {'de': 1314459}, 'id': 1314458, 'title': 'Gelebte Kooperation in Dornbirn'}}
Attribute description:

Translations

A translation contains the best practice example's data in a specific language.

Sample request: query translation

This is the description
GET https://bpl.api.tool.european-energy-award.org/v1/translation/1314461
Response:
{'action_type_adaptation': False, 'action_type_energy_poverty': False, 'action_type_mitigation': False, 'approval_date': '2019-08-14 07:55:15.061119', 'area_of_intervention': 'modal_shift_to_public_transport', 'cite': None, 'co2_reduction': None, 'co2_reduction_comment': None, 'community': 'Dornbirn', 'contact_person': None, 'description': 'short description', 'eea_advisor_contact': 'your.eee@advisor.contact', 'eea_area': 'mobility', 'energy_savings': None, 'example_description': '<p>Some richtext</p><p>contianing tags and more.</p>', 'files': {'1333929': {'filename': 'filename.docx', 'url': '/v1/example/1314460/file/1333929'}}, 'finance': None, 'id': 1314461, 'image': {'filename': 'image_filename.png', 'url': '/v1/example/1314460/image'}, 'image_caption': 'A beautiful image.', 'image_credits': 'Hans Moleman', 'implementation_cost': None, 'implementation_end_year': None, 'implementation_size_type': None, 'implementation_size_unit': None, 'implementation_size_value': None, 'implementation_start_year': 2011, 'implementation_status': 'ongoing', 'jobs_created': None, 'language': 'de', 'lessons_learned': None, 'players': None, 'quote': None, 'renewable_energy_produced': None, 'responsible_body': None, 'sector': 'transport', 'stakeholders_involved': None, 'title': 'Betriebliches Mobilitätsmanagement', 'type_of_policy_instrument': None, 'video_url': None, 'website_url': None}
Attribute description:
action_type_adaptation
Type: Boolean
action_type_energy_poverty
Type: Boolean
action_type_mitigation
Type: Boolean
approval_date
Type: Datetime
area_of_intervention
Values are dependent on the sector's value.
Type: Enum
Nullable
Sector: industry
Values: ['energy_efficiency_in_industrial_processes', 'energy_efficiency_in_buildings', 'renewable_energy', 'information_communication_technologies', 'other']
Sector: local_electricity
Values: ['hydroelectric_power', 'wind_power', 'photovoltaics', 'biomass_power_plant', 'combined_heat_power', 'smart_grids', 'other']
Sector: local_heat
Values: ['combined_heat_power', 'district_heating_cooling_plant', 'district_heating_cooling_network', 'other']
Sector: municipal
Values: ['building_envelope', 'renewable_energy', 'energy_efficiency', 'energy_efficiency_lighting', 'energy_efficiency_electrical', 'integrated_action', 'information_communication', 'behavioural_changes', 'other']
Sector: other
Values: ['urban_regeneration', 'waste_wastewater_mangement', 'tree_planting_in_urban_areas', 'agriculture_forestry_related', 'other']
Sector: public
Values: ['energy_efficiency', 'integrated_renewable_power', 'information_communication', 'other']
Sector: residential
Values: ['building_envelope', 'renewable_energy', 'energy_efficiency', 'energy_efficiency_lighting', 'energy_efficiency_electrical', 'integrated_action', 'information_communication', 'behavioural_changes', 'other']
Sector: tertiary
Values: ['building_envelope', 'renewable_energy', 'energy_efficiency', 'energy_efficiency_lighting', 'energy_efficiency_electrical', 'integrated_action', 'information_communication', 'behavioural_changes', 'other']
Sector: transport
Values: ['cleaner_efficient_vehicles', 'electric_vehicles_incl_infrastructure', 'modal_shift_to_public_transport', 'modal_shift_to_walking_cycling', 'car_sharing_pooling', 'improvement_of_logistics_urban_freight_transport', 'road_network_optimisation', 'mixed_use_development_sprawl_containment', 'information_communication_technologies', 'eco_driving', 'other']
cite
Type: String (unicode)
Nullable
co2_reduction
Type: Number
Nullable
co2_reduction_comment
Type: String (unicode)
Nullable
community
Type: String (unicode)
contact_person
Type: String (unicode)
Nullable
description
Short description. Maximum 300 characters.
Type: String (unicode)
eea_advisor_contact
Type: String (unicode)
Nullable
eea_area
Type: Enum
Values: ['development_spatial_planning_strategy', 'municipal_buildings_facilities', 'supply_disposal', 'mobility', 'internal_organisation', 'communication_cooperation']
energy_savings
Type: String (unicode)
Nullable
example_description
Detailed example description.
Type: String (Richtext)
files
Empty if no files are attached. Key value pair otherwise. Key is the file id value the file object. File object contains filename and file URL.
Type: Object
filename
Type: String
url
URL to query file.
Type: String
finance
Type: String (Richtext)
Nullable
id
Translation ID.
Type: Integer
image
Contains filename and url.
Type: Object
filename
Image filename.
Type: String
url
URL to query image.
Type: String
image_caption
Type: String (unicode)
image_credits
Type: String (unicode)
implementation_cost
Type: String (unicode)
Nullable
implementation_end_year
Type: Integer
Nullable
implementation_size_type
Type: String (unicode)
Nullable
implementation_size_unit
Type: String (unicode)
Nullable
implementation_size_value
Type: Number
Nullable
implementation_start_year
Type: Integer
Nullable
implementation_status
Type: Enum
Nullable
Values: ['ongoing', 'completed', 'postponed', 'not_started', 'new']
jobs_created
Type: String (unicode)
Nullable
language
Two character language abbreviation.
Type: String
lessons_learned
Type: String (Richtext)
Nullable
players
Type: String (Richtext)
Nullable
quote
Type: String (unicode)
Nullable
renewable_energy_produced
Type: String (unicode)
Nullable
responsible_body
Type: String (unicode)
Nullable
sector
Type: Enum
Nullable
Values: ['municipal', 'public', 'industry', 'tertiary', 'residential', 'transport', 'local_electricity', 'local_heat', 'other']
stakeholders_involved
Type: Enum
Nullable
Values: ['national_government', 'regional_government', 'local_government', 'academia', 'business_and_private_sector', 'trade_union', 'ngos_and_civil_society', 'citizens', 'other']
title
Language depended title of the best practice example.
Type: String (unicode)
type_of_policy_instrument
Values are dependent on the sector's value.
Type: Enum
Nullable
Sector: industry
Values: ['awareness_raising_training', 'energy_management', 'energy_certification_labelling', 'energy_performance_standards', 'energy_carbon_taxes', 'grants_subsidies', 'third_party_financing', 'not_applicable', 'other']
Sector: local_electricity
Values: ['awareness_raising_training', 'energy_suppliers_obligations', 'grants_and_subsidies', 'third_party_financing', 'public_procurement', 'building_standards', 'land_use_planning', 'not_applicable', 'other']
Sector: local_heat
Values: ['awareness_raising_training', 'energy_suppliers_obligations', 'grants_subsidies', 'third_party_financing', 'building_standards', 'land_use_planning_regulation', 'not_applicable', 'other']
Sector: municipal
Values: ['awareness_raising', 'energy_management', 'energy_certification', 'energy_suppliers_obligations', 'energy_carbon_taxes', 'grants_subsidies', 'third_party_financing', 'public_procurement', 'building_standards', 'land_use_planning_regulation', 'not_applicable', 'other']
Sector: other
Values: ['awareness_raising_training', 'land_use_planning', 'not_applicable', 'other']
Sector: public
Values: ['energy_management', 'energy_suppliers_obligations', 'third_party_financing', 'public_procurement', 'not_applicable', 'other']
Sector: residential
Values: ['awareness_raising', 'energy_management', 'energy_certification', 'energy_suppliers_obligations', 'energy_carbon_taxes', 'grants_subsidies', 'third_party_financing', 'public_procurement', 'building_standards', 'land_use_planning_regulation', 'not_applicable', 'other']
Sector: tertiary
Values: ['awareness_raising', 'energy_management', 'energy_certification', 'energy_suppliers_obligations', 'energy_carbon_taxes', 'grants_subsidies', 'third_party_financing', 'public_procurement', 'building_standards', 'land_use_planning_regulation', 'not_applicable', 'other']
Sector: transport
Values: ['awareness_raising_training', 'integrated_ticketing_charging', 'grants_subsidies', 'road_pricing', 'land_use_planning_regulation', 'transport_mobility_planning_regulation', 'public_procurement', 'voluntary_agreements_with_stakeholders', 'not_applicable', 'other']
video_url
Type: String
Nullable
website_url
Type: String
Nullable

Images

Every best practice example contains an image. The image source if provided by the translation.

Sample request: query image

This is the description
GET https://bpl.api.tool.european-energy-award.org/v1/example/1314461/image
Response:
binary data
Attribute description:

Files

A best practice example may contain attached files. File source is provided within a translation.

Sample request: query file

This is the description
GET https://bpl.api.tool.european-energy-award.org/v1/example/1314461/file/133392
Response:
binary data
Attribute description:

Error Codes

Error messages will always be returned in JSON format containing the key: 'error' and the error message as its according value.

400 Bad Request

Example error message:

{ "error": "400 Bad request: you are not authorized to access this resource." }

401 Unauthorized

Example error message:

{ "error": "401 Unauthorized: you are not authorized to access this resource." }

404 Not Found

Example error message:

{ "error": "404 Not found: no example exists with id '42'." }

405 Method Not Allowed

Only GET request are allowed.

Example error message:

{ "error": "405 Method Not Allowed: The method is not allowed for the requested URL." }

500 Internal Server Error

Example error message:

{ "error": "500 Internal Server Error: The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." }

Examples

HTML
Image
<img src="https://bpl.api.tool.european-energy-award.org/v1/example/42/image" alt="Image caption from translation"/>
Files
<a href="https://bpl.api.tool.european-energy-award.org/v1/example/42/file/42" download="Filename from translation"/>Filename from translation</a>