API usage

API Security and Authentication

The brAIn API suite is secured using AWS Cognito. All API calls require authentication to ensure secure and authorized access to data and functionalities.

Authentication Flow: OAuth 2.0 Client Credentials Grant

Partners and their applications will authenticate with the brAIn APIs using the OAuth 2.0 Client Credentials Grant flow. This flow is suitable for server-to-server communication where the client application itself is authenticating. To obtain an access token (JWT), you must make a POST request to the token endpoint:

Token Endpoint URL QA

https://auth-recometrics-partners.qa.datanumia.com/oauth2/token

Token example QA

curl -s -H "Content-Type: application/x-www-form-urlencoded" -X POST -u 'xxx:yyy' https://auth-recometrics-partners.qa.datanumia.com/oauth2/token \
 --data-urlencode 'grant_type=client_credentials' --data-urlencode 'scope=qa-b2b-brain-user-poolrs/api.read qa-b2b-brain-user-poolrs/api.write'

Token Endpoint URL Prod

https://auth-recometrics-partners.datanumia.com/oauth2/token

Token example PROD

curl -s -H "Content-Type: application/x-www-form-urlencoded" -X POST -u 'xxx:yyy' https://auth-recometrics-partners.datanumia.com/oauth2/token \
 --data-urlencode 'grant_type=client_credentials' --data-urlencode 'scope=b2b-brain-user-poolrs/api.read b2b-brain-user-poolrs/api.write'

Request Details: HTTP Method: POST Body Parameters: Your unique client_id & client_secret provided by Datanumia.

Using the Access Token

Once you receive the access_token, you must include it in the Authorization header of all subsequent API requests. Header Name: Authorization Header Value Format: Bearer [YOUR_ACCESS_TOKEN]

API Endpoints Overview

The brAIn API suite is logically separated into distinct services, each accessible via its own base URL and responsible for specific functionalities:

Simulation API

https://brain-simulation-api.datanumia.com/v1/advices This is the core API for energy consulting simulations. It allows partners to submit client and housing characteristics data to receive personalized energy equipment and service recommendations, along with estimated savings (financial, energy, CO2), payback periods, and eligibility scores. You can access a QA environement at https://brain-simulation-api.qa.datanumia.com/v1/advices This endpoint accepts multiple parameters that allow for fine-tuning the simulation. Here are the main input variables:

Variable name	Description	Type	Data
AMORTIZATION_METHOD	Amortization calculation method used for ROI computations	ENUM	Enum: FIXED_PRICE, PRICE_EVOLUTION
COUNTRY	Country code / country identifier	STRING	ISO-like country string
CUSTOMER_AFFINITY	Customer affinity segment	ENUM	Enum: BUDGET, INVESTMENT, PERFORMANCE
DOOR_COST	Estimated door replacement/insulation cost	DECIMAL	€
DOOR_HEATING_CONSUMPTION_SAVINGS_RATE	Expected heating savings rate from door work	DECIMAL	Ratio (0–1)
DOOR_TO_INSULATE_QUANTITY	Number of doors to insulate/replace	INT	≥ 0
DOOR_TARGET_MATERIAL_TYPE	Target door material	ENUM	Enum: PVC, ALU
DOOR_TARGET_TYPE	Target door type	ENUM	Enum: UNGLAZED_DOOR, SEMI_GLAZED_DOOR, FULLY_GLAZED_DOOR
ELECTRIC_VEHICLE_BATTERY_CAPACITY	EV battery capacity	DECIMAL	kWh
ELECTRIC_VEHICLE_HOUSING_RECHARGE_PRICE	Home charging electricity price for EV	DECIMAL	€
ELECTRIC_VEHICLE_PUBLIC_CHARGING_PRICE	Public charging electricity price for EV	DECIMAL	€/kWh
ELECTRIC_VEHICLE_RECHARGE_BREAKDOWN	Charging distribution (home/public)	OBJECT	HOUSING : DECIMAL, FREE : DECIMAL, PUBLIC : DECIMAL
ELECTRIC_VEHICLE_RECHARGE_PERCENTAGE	Charging share assumption	DECIMAL	Ratio / %
ELECTRIC_VEHICLE_RECHARGE_TIME	Target recharge time	DECIMAL	minutes
ELECTRICITY_CO2_EMISSION_FACTOR	Electricity CO2 emission factor	DECIMAL	kg/kWh
ELECTRICITY_PRICE	Electricity unit price	DECIMAL	€/kWh
ELECTRICITY_POINT_OF_DELIVERY	Electricity meter identifier	STRING	Identifier
ELECTRICITY_SELLING_PRICE	Electricity resale price	DECIMAL	€/kWh
GAS_CO2_EMISSION_FACTOR	Gas CO2 emission factor	DECIMAL	kg/kWh
GAS_PRICE	Gas unit price	DECIMAL	€/kWh
HEAT_PUMP_REQUIRED_ELECTRICITY_POWER	Required electrical power for heat pump	DECIMAL	kW
HEAT_PUMP_SUBVENTION	Heat pump subsidy	DECIMAL	€
ENEDIS_CLIENT_CONSENT	Customer consent for Enedis data usage	BOOL	true / false
HOUSING_ALTITUDE	Housing altitude	INT	meters
HOUSING_ATTIC_SURFACE	Attic surface	DECIMAL	m²
HOUSING_ATTIC_TYPE	Attic type	ENUM	Enum: CONVERTED, LOST, NONE
HOUSING_BASE_TEMPERATURE	Base calculation temperature	INT	°C
HOUSING_CEILING_HEIGHT	Average ceiling height	DECIMAL	meters
HOUSING_CONSTRUCTION_YEAR	Construction year	INT	YYYY
HOUSING_DOOR_RENOVATED	Doors renovated	BOOL	true / false
HOUSING_ELECTRIC_CONNECTION	Electrical connection type	ENUM	Enum: SINGLE_PHASE, THREE_PHASE
HOUSING_EVSE_MAX_POWER	Max EV charging power	DECIMAL	kW
HOUSING_EVSE_TYPE	EV charging equipment type	ENUM	Enum: NONE, HOUSING_PLUG, REINFORCED_PLUG, STATION
HOUSING_FUEL_PRICE	Heating fuel unit price	DECIMAL	€/L
HOUSING_HEATING_SEASON_OUTDOOR_TEMPERATURE	Outdoor temperature during heating season	DECIMAL	°C
HOUSING_HEATING_SETPOINT_TEMPERATURE	Heating temperature setpoint	DECIMAL	°C
HOUSING_INDOOR_ROOF_SURFACE	Indoor roof surface	DECIMAL	m²
HOUSING_INSULATION_FACTOR	Global insulation factor	DECIMAL	W/(m³.°C)
HOUSING_INSULATION_LEVEL	Global insulation level	ENUM	Enum: NEW_BUILDING, EXCELLENT, GOOD, NORMAL, OLD_BUILDING
HOUSING_INSULATION_WORK_PERFORMED	Global insulation work performed	BOOL	true / false
HOUSING_JOINERY_HEATING_CONSUMPTION_SAVINGS_MAX_RATE	Max savings rate from joinery	DECIMAL	Ratio (0–1)
HOUSING_JOINERY_INSULATION_SUBVENTION	Joinery insulation subsidy	DECIMAL	€
HOUSING_LAST_YEAR_ELECTRICITY_CONSUMPTION	Electricity consumption last year	DECIMAL	kWh
HOUSING_LAST_YEAR_GAS_HEATING_CONSUMPTION	Gas heating consumption last year	DECIMAL	kWh
HOUSING_LAST_YEAR_GAS_SANITARY_HOT_WATER_CONSUMPTION	Gas hot water consumption last year	DECIMAL	kWh
HOUSING_LAST_YEAR_MAX_POWER	Max power reached last year	DECIMAL	kW
HOUSING_LAST_YEAR_SUMMER_AVERAGE_DAILY_ELECTRICITY_CONSUMPTION	Avg daily summer consumption	DECIMAL	kWh
HOUSING_MAXIMUM_ROOF_EXPLOITABLE_LENGTH	Max exploitable roof length	DECIMAL	meters
HOUSING_MAXIMUM_ROOF_EXPLOITABLE_PERCENTAGE	Max usable roof share	DECIMAL	Ratio / %
HOUSING_MAXIMUM_ROOF_EXPLOITABLE_WIDTH	Max exploitable roof width	DECIMAL	meters
HOUSING_MUNICIPALITY_DENSITY_TYPE	Municipality density type	ENUM	Enum: MAJOR_URBAN_CENTRE, MIDDLE_URBAN_CENTRE, SMALL_TOWN, URBAN_BELT, RURAL_TOWN, RURAL_AREA_WITH_DISPERSED_SETTLEMENTS, RURAL_AREA_WITH_VERY_DISPERSED_SETTLEMENTS
HOUSING_NUMBER_OF_ROOMS	Number of rooms	INT	≥ 1
HOUSING_OCCUPATION_STATUS	Occupation status	ENUM	Enum: OWNER, TENANT
HOUSING_ORIENTATION	Main orientation	ENUM	Enum: EAST, WEST, NORTH, SOUTH, SOUTH_EAST, SOUTH_WEST, NORTH_EAST, NORTH_WEST
HOUSING_OUTDOOR_ROOF_SURFACE	Outdoor roof surface	DECIMAL	m²
HOUSING_PRINCIPAL_HEATING_DISTRIBUTION_SYSTEM	Heating distribution system	ENUM	Enum: UNDERFLOOR_HEATING, RADIATOR, HEAT_PUMP, OTHER
HOUSING_PRINCIPAL_HEATING_DISTRIBUTION_SYSTEM_ENERGY_SOURCE	Distribution energy source	ENUM	Enum: ELECTRICITY, HIGH_TEMPERATURE_WATER, LOW_TEMPERATURE_WATER, OTHER
HOUSING_PRINCIPAL_HEATING_PRODUCTION_SYSTEM	Heating production system	ENUM	Enum: BOILER, HEAT_PUMP, RADIATOR, OTHER
HOUSING_PRINCIPAL_HEATING_PRODUCTION_SYSTEM_AGE	Heating system age	DECIMAL	years
HOUSING_PRINCIPAL_HEATING_PRODUCTION_SYSTEM_COP	Heating system COP	DECIMAL	Unitless
HOUSING_PRINCIPAL_HEATING_PRODUCTION_SYSTEM_ENERGY_SOURCE	Heating energy source	ENUM	Enum: GAS, ELECTRICITY, FUEL, OTHER
HOUSING_PRINCIPAL_HEATING_SYSTEM_SURFACE	Heated surface	DECIMAL	m²
HOUSING_PRINCIPAL_HEATING_SYSTEM_VOLUME	Heated volume	DECIMAL	m³
HOUSING_REQUIRED_ELECTRICITY_HEATING_POWER	Required heating electrical power	DECIMAL	kW
HOUSING_REQUIRED_HEATING_POWER_PER_SQUARE_METER	Required heating power per m²	DECIMAL	W
HOUSING_RESIDENCE_TYPE	Residence type	ENUM	Enum: MAIN, SECONDARY
HOUSING_ROOF_LENGTH	Roof length	DECIMAL	meters
HOUSING_ROOF_RENOVATED	Roof renovated	BOOL	true / false
HOUSING_ROOF_SLOPE	Roof slope	DECIMAL	degrees
HOUSING_ROOF_WIDTH	Roof width	DECIMAL	meters
HOUSING_SANITARY_HOT_WATER_MANAGEMENT	Central hot water management	BOOL	true / false
HOUSING_SANITARY_HOT_WATER_PRODUCTION_SYSTEM_ENERGY_SOURCE	Hot water energy source	ENUM	Enum: GAS, ELECTRICITY, FUEL, OTHER
HOUSING_SHUTTERS_RENOVATED	Shutters renovated	BOOL	true / false
HOUSING_SUBSCRIBED_POWER	Subscribed electrical power	INT	kVA
HOUSING_SUBSCRIBED_POWER_TARGET	Target subscribed power	INT	kVA
HOUSING_SWIMMING_POOL_PRESENCE	Swimming pool presence	BOOL	true / false
HOUSING_TOTAL_SURFACE	Total living surface	DECIMAL	m²
HOUSING_TYPE	Housing type	ENUM	Enum: APARTMENT, HOUSE
HOUSING_WALL_RENOVATED	Wall renovated	BOOL	true / false
HOUSING_WINDOWS_RENOVATED	Windows renovated	BOOL	true / false
HOUSING_YEARLY_BOILER_CONSUMPTION	Boiler energy consumption	DECIMAL	kWh
HOUSING_YEARLY_BOILER_CONSUMPTION_COST	Boiler yearly cost	DECIMAL	€
HOUSING_YEARLY_BOILER_FUEL_CONSUMPTION	Boiler fuel consumption	DECIMAL	L
HOUSING_YEARLY_ELECTRICITY_CONSUMPTION_COST	Yearly electricity cost	DECIMAL	€
HOUSING_YEARLY_ELECTRICITY_SUBSCRIPTION_COST	Yearly subscription cost	DECIMAL	€
HOUSING_YEARLY_ELECTRICITY_TOTAL_COST	Total yearly electricity cost	DECIMAL	€
HOUSING_YEARLY_HEATING_CONSUMPTION	Yearly heating consumption	DECIMAL	kWh
HOUSING_YEARLY_HEATING_CONSUMPTION_COST	Yearly heating cost	DECIMAL	€
HOUSING_ZIP_CODE	Postal code	STRING	5 digits (FR)
MECHANICAL_VENTILATION_SYSTEM_TYPE	Ventilation system type	ENUM	Enum: SINGLE_FLOW, DOUBLE_FLOW, NONE
MECHANICAL_VENTILATION_SYSTEM_INSTALLATION_SUBVENTION	Ventilation subsidy	DECIMAL	€
PATIO_DOOR_COST	Patio door cost	DECIMAL	€
PATIO_DOOR_HEATING_CONSUMPTION_SAVINGS_RATE	Patio door savings rate	DECIMAL	Ratio (0–1)
PATIO_DOOR_TO_INSULATE_QUANTITY	Patio door quantity	INT	≥ 0
PATIO_DOOR_TARGET_MATERIAL_TYPE	Patio door material	ENUM	Enum: PVC, ALU
PATIO_DOOR_CASEMENT_QUANTITY	Patio door casement quantity	INT	≥ 0
RECHARGED_VEHICLE_BATTERY_CAPACITY	Recharged vehicle battery capacity	DECIMAL	kWh
REFERENCE_COOLING_TEMPERATURE	Reference cooling temperature	INT	°C
REPLACE_THERMAL_VEHICLE_WITH_ELECTRIC_VEHICLE_SUBVENTION	EV replacement subsidy	DECIMAL	€
ROAD_TYPE_BREAKDOWN	Road type distribution	OBJECT	Distribution by type of road of journeys made by car over one year (sum between 0 & 1). CITY : DECIMAL, COUNTRYSIDE : DECIMAL, HIGHWAY : DECIMAL
ROOF_INSULATION_SUBVENTION	Roof insulation subsidy	DECIMAL	€
SOLAR_PANEL_INSTALLATION_SUBVENTION	Solar panel subsidy	DECIMAL	€
SOLAR_PANEL_INSTALLATION_ZONE	PV installation zone	ENUM	Enum: ROOF, NONE
SOLAR_PANEL_INSTALLATION_ZONE_TARGET	Target PV installation zone	ENUM	Enum: ROOF, NONE
SOLAR_PANEL_SELF_CONSUMPTION_RATE	Self-consumption rate	DECIMAL	Ratio (0–1)
SOLAR_PANEL_TYPE	Solar panel type	ENUM	Enum: PHOTOVOLTAIC, NONE
SHUTTER_COST	Shutter cost	DECIMAL	€
SHUTTER_HEATING_CONSUMPTION_SAVINGS_RATE	Shutter savings rate	DECIMAL	Ratio (0–1)
SHUTTER_TO_INSULATE_QUANTITY	Shutter quantity	INT	≥ 0
SHUTTER_TARGET_MATERIAL_TYPE	Shutter material	ENUM	Enum: PVC, ALU
SHUTTER_TARGET_TYPE	Shutter type	ENUM	Enum: SWING_SHUTTER, ROLLING_SHUTTER, LOUVERED_SHUTTER
THERMAL_VEHICLE_ENERGY_COST	Thermal vehicle energy cost	DECIMAL	€/L
UPGRADE_EVSE_SUBVENTION	EVSE upgrade subsidy	DECIMAL	€
VEHICLE_CONSUMPTION_BREAKDOWN	Vehicle consumption breakdown	OBJECT	CITY : DECIMAL, COUNTRYSIDE : DECIMAL, HIGHWAY : DECIMAL
VEHICLE_CONSUMPTION_BREAKDOWN_TARGET	Vehicle consumption breakdown target	OBJECT	CITY : DECIMAL, COUNTRYSIDE : DECIMAL, HIGHWAY : DECIMAL
VEHICLE_ENERGY_SOURCE	Vehicle energy source	ENUM	Enum: PETROL, DIESEL, ELECTRICITY, OTHER
VEHICLE_REGISTRATION_YEAR	Registration year	INT	YYYY
VEHICLE_TYPE	Vehicle type	ENUM	Enum: MINI_CITY_CAR, CITY_CAR, COMPACT, FAMILY_SEDAN, ROAD_SEDAN, MONOSPACE, SUV, LUDOSPACE, NONE
VEHICLE_TYPE_TARGET	Target vehicle type	ENUM	Enum: MINI_CITY_CAR, CITY_CAR, COMPACT, FAMILY_SEDAN, ROAD_SEDAN, MONOSPACE, SUV, LUDOSPACE, NONE
VEHICLE_YEARLY_CONSUMPTION	Yearly vehicle consumption	DECIMAL	L
VEHICLE_YEARLY_TRAVELLED_DISTANCE	Yearly travelled distance	DECIMAL	km
VEHICLE_YEARLY_TRAVELLED_DISTANCE_BREAKDOWN	Travel distance breakdown	OBJECT	CITY : INT, COUNTRYSIDE : INT, HIGHWAY : INT
WALL_INSULATION_SUBVENTION	Wall insulation subsidy	DECIMAL	€
WINDOW_COST	Window cost	DECIMAL	€
WINDOW_HEATING_CONSUMPTION_SAVINGS_RATE	Window savings rate	DECIMAL	Ratio (0–1)
WINDOW_CASEMENT_QUANTITY	Window casement quantity	INT	≥ 0
WINDOW_TO_INSULATE_QUANTITY	Window quantity	INT	≥ 0
WINDOW_TARGET_MATERIAL_TYPE	Window material	ENUM	Enum: ALU, PVC

Administration API

brain-admin-api.datanumia.com This API is dedicated to the management of client data and custom variables. It allows partners to retrieve, create, update, and delete client profiles. It also handles the configuration and retrieval of custom parameters specific to each commercial partner (e.g., tariff rates,electrcity price…).

Biling

brain-billing-api.datanumia.com This API provides functionalities for tracking and administration of billing related to the recometrics service usage. It allows Datanumia and potentially partners to monitor API consumption, generate billing reports, and manage subscription details. A comprehensive Swagger (OpenAPI) specification for all Recometrics APIs is available at the bottom of this documentation. This specification provides detailed information on all endpoints, models, and authentication mechanisms, allowing for easy exploration and testing.

General presentation

Recometrics API

Recometrics Desk

REST API

API Security and Authentication

Authentication Flow: OAuth 2.0 Client Credentials Grant

Token Endpoint URL QA

Token example QA

Token Endpoint URL Prod

Token example PROD

Using the Access Token

API Endpoints Overview

Simulation API

Administration API

Biling

General presentation

Recometrics API

Recometrics Desk

REST API

​API Security and Authentication

​Authentication Flow: OAuth 2.0 Client Credentials Grant

​Token Endpoint URL QA

​Token example QA

​Token Endpoint URL Prod

​Token example PROD

​Using the Access Token

​API Endpoints Overview

​Simulation API

​Administration API

​Biling

API Security and Authentication

Authentication Flow: OAuth 2.0 Client Credentials Grant

Token Endpoint URL QA

Token example QA

Token Endpoint URL Prod

Token example PROD

Using the Access Token

API Endpoints Overview

Simulation API

Administration API

Biling