AthausDocs

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:

PartGermany (de)
Default currencyEUR
Unit of areasSQUARE_METER
Disclosures a listing needs to be publishedthe energy certificate, or the statement that none is available or necessary
The countrySpecific section it ownsde, 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.currency defaults to the currency of the profile, and data.spaces.spaceMeasureUnit is 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 countrySpecific sections closed to members it does not define. Athaus sends the German extras in userDefined with the prefix de.:
NameContent
de.livingSpaceStandardthe basis of the living space figure: WOFLV, DIN_277 or UNKNOWN
de.usableSpaceStandardthe same for the usable space
de.siteCoverageRatiothe share of the plot that may be built over
de.floorAreaRatiothe floor area per plot area
de.developmentStatethe 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

On this page