REST API: country profiles
The core of the API is the same for every country. What differs per country sits in a profile. Germany is the first.
Last updated:
The API has one core and one profile per country. The core is the same everywhere: the shape of a listing, the ids, the errors, the pagination. A country profile adds what the law or the market of that country needs. Nothing in the core mentions a country.
A profile carries four things:
| Part | Germany (de) |
|---|---|
| Default currency | EUR |
| Unit of areas | SQUARE_METER |
| Disclosures a listing needs to be published | the energy certificate, or the statement that none is available or necessary |
The countrySpecific section it owns | de, with the energy certificates under data.energy.countrySpecific.de |
Germany is the only profile today. More countries arrive as more profiles, and the core does not change for them. GET /v1/me lists the profiles of your office under profiles.
One example: the energy certificate
A German residential listing states its energy certificate in data.energy.countrySpecific.de.energyCertificates. This is the energy member of a listing:
{
"countrySpecific": {
"de": {
"energyCertificates": [
{
"certificateType": "ENEV2014",
"certificateBasedOn": "CONSUMPTION",
"efficiencyClass": "C",
"validUntil": "2031-05-31",
"yearOfConstructionBuilding": 1998,
"primaryEnergySource": "GAS"
}
]
}
}
}A draft may leave it out. A listing without it, and without the statement NOT_AVAILABLE, NOT_NECESSARY or AT_VISIT as certificateType, cannot be published.
What a profile decides
- Currency and unit.
data.prices.currencydefaults to the currency of the profile, anddata.spaces.spaceMeasureUnitis the unit of the profile. Both are members of the standard, so a client that sends them explicitly never depends on the profile. - Required data. What a published listing must state is a profile rule. A draft is never held back by it.
- Extra data. The standard keeps its
countrySpecificsections closed to members it does not define. Athaus sends the German extras inuserDefinedwith the prefixde.:
| Name | Content |
|---|---|
de.livingSpaceStandard | the basis of the living space figure: WOFLV, DIN_277 or UNKNOWN |
de.usableSpaceStandard | the same for the usable space |
de.siteCoverageRatio | the share of the plot that may be built over |
de.floorAreaRatio | the floor area per plot area |
de.developmentState | the state of development of a plot, for example BUILDING_READY |
A country without a profile
A request with a countrySpecific section for a country that has no profile is answered with 400 and the code profile_unsupported. Nothing is written. Leave the section out, or ask for the country.
An inquiry carries the German statement of eligibility for subsidised housing in seeker.countrySpecific.de.hasSubsidizedHousingCertificate, the same way.
Keep reading
REST API: listings in the OpenImmo 2.0 shape
Read and write listings in the shape of OpenImmo 2.0. Two ids, drafts, receipts, warnings, and every member of a listing.
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
API error codes: what each code means
Every code the REST API returns in the member code of a problem, with its HTTP status and meaning. Generated from the contract.