Skip to content

Queries

Jump to bottom
kluknowledgecube edited this page May 1, 2025 · 20 revisions

Important

All examples below are based on fictional data and not related to real decisions made by municipal boards.

Authorisation

In order to access GraphQL API on huslejenaevn.dk, an API key is required. The API key must be provided as a custom HTTP Header named X-API-KEY such as:

X-API-KEY: a74b6864-aa0f-4ded-b626-f5cde4ba6759

Note

The above API key is not valid and just an example. Please contact naevn@sbst.dk for obtaining a valid API key. You will need to provide contact information and your purpose of access to these resources.

A valid API key authorise access to all resources on the GraphQL API endpoint, hence all query objects.

Query objects

The GraphQL API endpoint exposes six query objects:

Object Description
publications Information about specific publications made by municipal boards.
addresses Information about specific addresses where decisions have been made about level of rents.
decisions Information about specific decisions made by municipal boards.
pagedPublications Paged object about publications to improve performance when querying data.
pagedAddresses Paged object about addresses to improve performance when querying data.
pagedDecisions Paged object about decisions to improve performance when querying data.
laws Information about specific laws which are applicable for decisions made by municipal boards.
municipalities Information about specific municipalities of Denmark.

It is highly recommended to use the paged query objects to improve performance and limit size of responses (payload).

Publications

publications and pagedPublications provides information about addresses with ongoing or completed disputes or preliminary assessments submitted to Rent boards (da: huslejenævn) and Resident complaints boards (da: beboerklagenævn) in the municipalities of Denmark. Information about any specific decision made are not available - such correlation are not allowed hence by design.

Addresses

addresses and pagedAddresses provides information about addresses and their rent level (da: huslejeniveau) where decisions have been made by the Rent boards (da: huslejenævn) and Resident complaints boards (da: beboerklagenævn) in the municipalities of Denmark in accordance to level of rent. Level of rent for multiple addresses can be based on the same decision. Information about the specific decision are not available - such correlation are not allowed hence by design.

Decisions

decisions and pagedDecisions provides information about decisions (da: afgørelser) made by the Rent boards (da: huslejenævn) and Resident complaints boards (da: beboerklagenævn) in the municipalities of Denmark. A Decision can be based on multiple addresses. Information about addresses are not available - such correlation are not allowed hence by design.

A decision can contain a reference to a decision document which must be fetched separately. The decision document is in the format of Portable Document Format (PDF).

Read more about fetching decisions documents on the Documents pages.

Laws

laws provide information about laws (da: lovgivning) which are applicable for decisions made by municipal boards. Several laws are applicable as statutory basis (da: lovhjemmel) when municipal boards make formal decisions. Decisions are referenced to these laws.

Municipalities

municipalities provides information about municipalities of Denmark. Decisions are made by the Rent boards (da: huslejenævn) and Resident complaints boards (da: beboerklagenævn) boards in the municipalities of Denmark.

Pagination

Pagination solves the problem of having very large sets of data passed once by giving the client the ability to fetch a set in smaller chunks.

GraphQL API on huslejenaevn.dk uses the Connection Pattern to solve this. Connections are a standardized way to expose pagination to clients.

Addresses and Decisions are provided in paged query objects named pagedAddresses and pagedDecisions. An example of a query of paged adresses skipping the first 15 and taking only 1 address looks like this:

query {
  pagedAddresses(skip: 15, take: 1) {
    items {
      bfeIdentifierForPieceOfLand
      bfeIdentifierForUnit
      designation
      district
      floorIdentifier
      id
      municipalityCode
      municipalityName
      postalNumber
      streetBuildingIdentifier
      streetName
      suiteIdentifier
      supplementaryName
      rent {
        categoryOfRent
        dateOfRentDetermination
        declarationOfRent
        grossArea
        methodOfRentDetermination
        rent
      }
      coordinates {
        x
        y
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
    totalCount
  }
}

Which could returns:

{
  "data": {
    "pagedAddresses": {
      "items": [
        {
          "bfeIdentifierForPieceOfLand": 8721499,
          "bfeIdentifierForUnit": null,
          "designation": "Korsbæk Ødevej 15, st. tv, 8000 Aarhus C",
          "district": "Aarhus C",
          "floorIdentifier": "st",
          "id": "4572971a-4260-4693-ba73-50bea1c9425a",
          "municipalityCode": "0751",
          "municipalityName": "Aarhus Kommune",
          "postalNumber": 8000,
          "streetBuildingIdentifier": "15",
          "streetName": "Korsbæk Ødevej",
          "suiteIdentifier": "tv",
          "supplementaryName": "",
          "rent": {
            "categoryOfRent": "MONTHLY_RENT",
            "dateOfRentDetermination": "2016-11-11T10:57:13.004+01:00",
            "declarationOfRent": "TENANCY_SPECIFIC_RENT",
            "grossArea": 45,
            "methodOfRentDetermination": "BASED_ON_COMPARABLE_RENTS",
            "rent": 7863
          },
          "coordinates": {
            "x": 10.187227249145508,
            "y": 56.14365768432617
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": true
      },
      "totalCount": 3735
    }
  }
}

This is a very efficient way to traverse through large sets of data. Pagination can be combined with both filtering and sorting.

Filtering

For both filtering and sorting data, GraphQL API for huslejenaevn.dk uses Input types in order to group a set of arguments together, and then be used as an argument to another field.

An example of a query for addresses where streetName should be filtrered to the fictional: "Korsbæk Ødevej" looks like this:

query {
  addresses(where: { streetName: { contains: "Korsbæk Ødevej" } }) {
    bfeIdentifierForPieceOfLand
    bfeIdentifierForUnit
    designation
    district
    floorIdentifier
    id
    municipalityCode
    postalNumber
    streetBuildingIdentifier
    streetName
    suiteIdentifier
    supplementaryName
    rent {
      categoryOfRent
      dateOfRentDetermination
      declarationOfRent
      grossArea
      methodOfRentDetermination
      rent
    }
    coordinates {
      x
      y
    }
    municipalityName
  }
}

Which could return:

{
  "data": {
    "addresses": [
      {
        "bfeIdentifierForPieceOfLand": 6012666,
        "bfeIdentifierForUnit": null,
        "designation": "Korsbæk Ødevej 15, st. tv, 2300 København S",
        "district": "København S",
        "floorIdentifier": "st",
        "id": "39fdd618-7e0b-4df0-938c-6a10c2be1295",
        "municipalityCode": "0101",
        "postalNumber": 2300,
        "streetBuildingIdentifier": "15",
        "streetName": "Korsbæk Ødevej",
        "suiteIdentifier": "tv",
        "supplementaryName": "",
        "rent": {
          "categoryOfRent": "MONTHLY_RENT",
          "dateOfRentDetermination": "2015-02-04T10:55:05.729+01:00",
          "declarationOfRent": "TENANCY_SPECIFIC_RENT",
          "grossArea": 109,
          "methodOfRentDetermination": "BASED_ON_COMPARABLE_RENTS",
          "rent": 10910
        },
        "coordinates": {
          "x": 12.612525939941406,
          "y": 55.645957946777344
        },
        "municipalityName": "Københavns Kommune"
      }
    ]
  }
}

When filtering, it is also possible to use and and or with multiple arguments like this:

query {
  addresses(
    where: {
      or: [
        { bfeIdentifierForPieceOfLand: { eq: 7887348 } }
        { bfeIdentifierForUnit: { eq: 7887348 } }
      ]
    }
  ) {
    bfeIdentifierForPieceOfLand
    bfeIdentifierForUnit
    designation
    district
    floorIdentifier
    id
    municipalityCode
    municipalityName
    postalNumber
    streetBuildingIdentifier
    streetName
    suiteIdentifier
    supplementaryName
    coordinates {
      x
      y
    }
    rent {
      categoryOfRent
      dateOfRentDetermination
      declarationOfRent
      grossArea
      methodOfRentDetermination
      rent
    }
  }
}

Which could return:

{
  "data": {
    "addresses": [
      {
        "bfeIdentifierForPieceOfLand": 7887348,
        "bfeIdentifierForUnit": null,
        "designation": "Korsbæk Ødevej 15, st. tv, 2450 København SV",
        "district": "København SV",
        "floorIdentifier": "st",
        "id": "2671c48a-ed09-49e1-bae9-6843de5bf544",
        "municipalityCode": "0101",
        "municipalityName": "Københavns Kommune",
        "postalNumber": 2450,
        "streetBuildingIdentifier": "15",
        "streetName": "Korsbæk Ødevej Gade",
        "suiteIdentifier": "tv",
        "supplementaryName": "",
        "coordinates": {
          "x": 12.534740447998047,
          "y": 55.6505126953125
        },
        "rent": {
          "categoryOfRent": "MONTHLY_RENT",
          "dateOfRentDetermination": "2011-05-25T10:54:50.259+02:00",
          "declarationOfRent": "TENANCY_SPECIFIC_RENT",
          "grossArea": 86,
          "methodOfRentDetermination": "BASED_ON_COMPARABLE_RENTS",
          "rent": 16698
        }
      }
    ]
  }
}

Filtering can be combined with pagination and sorting as well.

Sorting

An example of a query for addresses where results should be sorted by postalNumber descendingly looks like this:

query {
  addresses(order: { postalNumber: DESC }) {
    bfeIdentifierForPieceOfLand
    bfeIdentifierForUnit
    designation
    district
    floorIdentifier
    id
    municipalityCode
    municipalityName
    postalNumber
    streetBuildingIdentifier
    streetName
    suiteIdentifier
    supplementaryName
    coordinates {
      x
      y
    }
    rent {
      categoryOfRent
      dateOfRentDetermination
      declarationOfRent
      grossArea
      methodOfRentDetermination
      rent
    }
  }
}

Which could returns:

{
  "data": {
    "addresses": [
      {
        "bfeIdentifierForPieceOfLand": 5530065,
        "bfeIdentifierForUnit": null,
        "designation": "Korsbæk Ødevej 13, 1. th, 9990 Skagen",
        "district": "Skagen",
        "floorIdentifier": "1",
        "id": "e9fb2c6f-6768-4ada-9d85-8a079b9ed536",
        "municipalityCode": "0813",
        "municipalityName": "Frederikshavn Kommune",
        "postalNumber": 9990,
        "streetBuildingIdentifier": "13",
        "streetName": "Korsbæk Ødevej",
        "suiteIdentifier": "th",
        "supplementaryName": "",
        "coordinates": {
          "x": 10.593524932861328,
          "y": 57.72214889526367
        },
        "rent": {
          "categoryOfRent": "ANNUAL_RENT_PER_SQUARE_METERS",
          "dateOfRentDetermination": "2008-11-21T10:56:00.978+01:00",
          "declarationOfRent": "TENANCY_SPECIFIC_RENT",
          "grossArea": 113,
          "methodOfRentDetermination": "BASED_ON_COMPARABLE_RENTS",
          "rent": 272
        }
      },
      ...
      {
        "bfeIdentifierForPieceOfLand": 6033908,
        "bfeIdentifierForUnit": null,
        "designation": "Korsbæk Byvej 15, st. tv, 1050 København K",
        "district": "København K",
        "floorIdentifier": "st",
        "id": "a74215d9-c31c-4923-ab7f-f7d2b0c6e4d0",
        "municipalityCode": "0101",
        "municipalityName": "Københavns Kommune",
        "postalNumber": 1050,
        "streetBuildingIdentifier": "15",
        "streetName": "Korsbæk Byvej",
        "suiteIdentifier": "tv",
        "supplementaryName": "",
        "coordinates": {
          "x": 12.584808349609375,
          "y": 55.679443359375
        },
        "rent": {
          "categoryOfRent": "MONTHLY_RENT",
          "dateOfRentDetermination": "2007-09-13T10:57:53.654+02:00",
          "declarationOfRent": "TENANCY_SPECIFIC_RENT",
          "grossArea": 116,
          "methodOfRentDetermination": "BASED_ON_COMPARABLE_RENTS",
          "rent": 16537
        }
      }
    ]
  }
}

Sorting can be done ascending (ASC) and descending (DESC).

Sorting can be combined with pagination and filtering as well.

Clone this wiki locally