Data Schema - Selfmade Energy Developer Documentation

API version 2

Please note that this documentation covers version 2 (v2) of the API which was released in April 2023. We encourage all partners to only use this version going forward. If you are still using v1 please refer to the Version 1 documentation and the upgrade guide.

Open API specification

The API data structure is provided as an OpenAPI 3.0 specification (JSON).

Example response

{
  "id": 1234,
  "created": "2023-02-27T18:33:23.013575+01:00",
  "location": {
    "id": 567,
    "name": "Niederlassung München",
  },
  "product": {
    "id": 890,
    "name": "PV-Anlage, 415 Wp, Kauf",
  },
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "street": "Hauptstraße",
    "street_number": "123",
    "zipcode": "12345",
    "city": "Berlin",
    "coordinate": {
      "lat": 52.12345,
      "lng": 13.12345
    },
    "email": "john.doe@example.com",
    "phone": "+491234567890",
    "year_of_birth": 1978
  },
  "parameters": {
    "house_type": "detached house",
    "energy_consumption": 7000.0,
    "is_interested_in_emobility": true,
    "is_interested_in_heat_pump": true,
    "is_interested_in_batteries": true,
    "roof_angle": 30,
    "roof_orientation": 155,
    "roof_area": "more-than-100-qm",
    "roof_material": "clay",
    "roof_renovated_period": "new_building",
    "installation_time": "1-6 months",
    "financing": ["buy", "rent"],
    "customer_is_owner": true
  },
  "calculations": {
    "netto_capacity": 12.75,
    "suitability": "verygood",
    "pv_area": {
      "well_suited": 323.9,
      "suited": 95.9,
      "barely_suited": 0
    },
    "max_energy": 74758,
    "number_of_panels": 28,
    "yearly_yield": 9174,
    "autarky": 67,
    "co2_savings": 4.2
  },
  "prices": {
    "with_battery": 23456.78,
    "without_battery": 12345.67
  },
  "photos": [
    {
      "type": "gable view",
      "url": "https://images.example.com/8491384-1D92A491/gable-view/1234567-8901234.jpg",
      "score": "good"
    },
    {
      "type": "house and surroundings",
      "url": "https://images.example.com/8491384-1D92A491/house-and-surroundings/1234567-8901234.jpg",
      "score": "good"
    },
    {
      "type": "meter cabinet",
      "url": "https://images.example.com/8491384-1D92A491/meter-cabinet/1234567-8901234.jpg",
      "score": "good"
    },
    {
      "type": "roof surface",
      "url": "https://images.example.com/8491384-1D92A491/roof-surface/1234567-8901234.jpg",
      "score": "good"
    },
    {
      "type": "tiles",
      "url": "https://images.example.com/8491384-1D92A491/tiles/1234567-8901234.jpg",
      "score": "good"
    }
  ],
  "legal": {
    "terms_and_conditions_accepted": true,
    "data_privacy_accepted": true
  }
}

Schemas

`PVLead`

This is the root of the response and has some meta information about the lead as well as all other payload data nested below it.

Property	Type	Description
`id` *	`integer`
`lead_type`	`string`
`created` *	`string(date-time)`	Date and time the lead was created
`location` *	`Location`	Location of the partner
`product` *	`ExportProduct`	Product offered by the partner
`customer` *	`Customer`	Customer who created the lead
`legal` *	`Legal`	Legal documents the customer agreed to
`parameters` *	`PVParameters`	Parameters given by the customer
`calculations` *	`PVCalculations`	Calculations made based on given parameters
`prices` *	`PVPrices`	Prices shown to the customer based on the pricing information provided by the partner
`photos` *	`[Photo]`	Photos uploaded by the customer

`Location`

PV companies have one or more locations (company sites). This section identifies the location the lead was created with.

Property	Type	Description
`id` *	`integer`	Location identifier
`name` *	`string`	Location name

`Product`

PV companies can offer multiple products on our platform. The most common differentiator is the type of financing (buying vs. renting). This section identifies the product that was offered to the user.

Property	Type	Description

`Customer`

Every Lead is associated with one Customer which represents the prospective customer.

Property	Type	Description
`first_name` *	`string`	First name
`last_name` *	`string`	Last name
`year_of_birth`	`integer`	Year of birth of the customer – this is only prompted when a renting option is selected in `financing`
`street` *	`string`	Street name
`street_number` *	`string`	Street number
`zipcode` *	`string`	Zip code
`city` *	`string`	City
`coordinate` *	`Coordinates`	Geo coordinates for the given address
`email` *	`string`	Confirmed e-mail address
`phone` *	`string`	Phone number

`Coordinate`

The geographic coordinate for the given address.

Property	Type	Description

`PVParameters`

All the information given by the customer in their inquiry. These have already been matched with the partner's requirements so that only matching leads are pushed.

Property	Type	Description
`house_type` *	`string` – one of `detached house` `semi-detached house` `townhouse` `end-terrace house` `apartment building` `non-residential`	Type of house
`energy_consumption` *	`number(double)`	Energy consumption in kWh per year
`is_interested_in_emobility` *	`boolean`	Whether the customer is also interested in e-mobility products
`is_interested_in_heat_pump` *	`boolean`	Whether the customer is also interested in a heat pump product
`is_interested_in_batteries` *	`boolean`	Whether the customer is also interested in a battery product
`roof_angle` *	`integer`	Angle of the roof in degrees – 0° is flat
`roof_orientation` *	`integer`	Orientation of the roof in degrees – 0° is North
`roof_area`	`string`	Size of the roof in m²
`roof_material` *	`string`	Material of the roof
`roof_renovated_period` *	`string`	When the roof was built or last renovated
`installation_time` *	`string` – one of `right away` `1-6 months` `6-12 months` `not planned yet` `unknown`	When the customer would like the installation to happen
`customer_is_owner` *	`boolean`	Whether the customer is the owner of the house
`financing` *	`[` – one of `buybuy` `rentrent` `]`	Financing options the customer is interested in

`PVCalculations`

The results of the calculations based on the parameters given by the customer.

Property	Type	Description
`netto_capacity` *	`number(double)`	Netto capacity of the battery in kWp
`suitability` *	`string` – one of `verygood` `good` `okay` `none` `unknown`	Suitability of the roof for PV – `none` means not suitable, `unknown` means not calculated
`pv_area` *	`PVArea`	Roof areas and their suitability for mounting a PV plant.
`max_energy` *	`number(double)`	Maximum possible energy yield (on all roof surfaces classified as at least suitable) in kWh/year
`number_of_panels` *	`integer`	Total size of all plants in number of modules
`kwp` *	`number(double)`	Peak power of the PV plant in kWp
`yearly_yield` *	`number(double)`	Yearly yield of the PV plant in kWh/year
`autarky` *	`integer`	Degree of autarky in percent received with given solar plant
`co2_savings` *	`number(double)`	CO₂ savings in tons per year

`PVArea`

Information about roof areas and their suitabilty for mounting a PV plant.

Property	Type	Description
`well_suited` *	`number(double)`	Area of the roof in m² that is well suited
`suited` *	`number(double)`	Area of the roof in m² that is suited
`barely_suited` *	`number(double)`	Area of the roof in m² that is barely suited

`PVPrices`

Prices shown to the customer based on the pricing information provided by the partner

Property	Type	Description
`with_battery` *	`number(double)`	Price for solar plant with battery
`without_battery` *	`number(double)`	Price for solar plant without battery – possibly identical to `with_battery` when partner only offers solar plants with battery

`Photo`

Different types of photos uploaded by the customer to further substantiate their requirements and parameters.

Property	Type	Description
`type`	`string` – one of `roof surface` `house and surroundings` `gable view` `meter cabinet` `tiles`	Type of the image
`url` *	`string(uri)`	URL to the image file
`score` *	`string` – one of `good` `medium` `bad`	How the image was rated by the AI

`Legal`

Information about the legal documents the customer agreed to.

Property	Type	Description
`terms_and_conditions_accepted` *	`boolean`	Whether the customer agreed to the Selfmade Energy terms and conditions
`data_privacy_accepted` *	`boolean`	Whether the customer agreed to the Selfmade Energy data privacy policy