Skip to content

API Documentation

Jump to bottom
Michael Bucher edited this page May 30, 2021 · 20 revisions

General Use

All API methods can be called via /api/method_name. There is no authentication involved as all data and software in this project is open source. Data cannot be altered, only retrieved. API methods make use of the HTTP methods GET and POST. Where applicable, is specified below.

Note: The flask API also provides a Swagger-based API documentation. Once the application is started, it can be accessed with the following URL: http:localhost:5000/apidocs.

API methods

allListings

This method is used to retrieve all available listings. Listings cannot be filtered with this method, however, the retrieved data attributes (per listing) can be chosen by the user. For this purpose, the method implements two HTTP methods: GET and POST. The GET method can be used to retrieve listings with a pre-defined (default) set of attributes, while the POST methods allows for customized retrieval. The default attributes are the following:

  • id integer

    An integer key for uniquely identifying the listing.

  • name string

    The name of the listing, as provided by the host.

  • description string

    A description of the listing, as provided by the host.

  • price float

    The price of the hosted property (in $).

  • picture_url string

    An url to a picture of the listing.

  • bedrooms integer

    The number of bedrooms in the accommodation.

  • bathrooms integer

    The number of bedrooms in the accommodation.

  • accommodates integer

    The number of accommodates.

  • property_type string

    The type of property.

  • neighbourhood string

    The neighbourhood the accommodation is in.

  • longitude string

    Longitudinal position of the accommodation.

  • latitude string

    Latitudinal position of the accommodation.

Whether a GET or POST request is made, the request response is always a JSON array of objects. Two HTML codes are important for this method:

  • 200: Everything was okay.
  • 400: Oops, something went wrong. Check the error message and make sure data is correctly submitted.

GET method

Per default this method retrieves all listings including such that contain empty values for certain attributes. If you want to avoid this behaviour, please use the POST method instead (see below).

Example (Python):

>>> import requests
>>> r = requests.get('http://localhost:5000/api/allListings')
>>> r.json()
[{'id': 2015.0,
  'name': 'Berlin-Mitte Value! Quiet courtyard/very central',
  'description': 'Great location!  30 of 75 sq meters. This wood floored/high ceiling typical Berlin "Altbau" section of an apartment consists of 1 simple large room, a small kitchen and a bathroom + shower. The apartment is in Mitte, close to Prenzlauer Berg/Mauerpark. Perfect for short visits, singles or couples. Your section is closed from the rest of the bigger flat wich is not noticeable. Private entrance, kitchen and full bathroom. You will not be sharing your space in any way. A+++ location! This „Einliegerwohnung“ is an extention of a larger apartment with a separate entrance, bathroom and kitchen. The door to the rest of the apartment is soundproof, hidden, locked and barely noticable (behind mirror in pictures). Your 30 sq meters are facing a quiet courtyard. This wood floored/high ceiling typical Berlin "Altbau" apartment consists of 1 large room with a large double bed, optionally with an extra matress for a 3rd guest), a small kitchen suitable for preparing simple meals, a bathroom + shower',
  'neighbourhood': 'Mitte',
  'latitude': 52.53454,
  'longitude': 13.40256,
  'accommodates': 3.0,
  'bathrooms': 1.0,
  'bedrooms': 1.0},
...
]

POST method

In order to use this method, provide the request as JSON object. The following parameters/keys are relevant in this matter:

  • fields JSON array required

    This parameter specifies which attributes for each listing should be retrieved. It should be provided as JSON array of string values.

    Example usage (value): ["price", "bedrooms"]

  • force_fields boolean optional

    This parameter defines whether only listings should be retrieved that contain a non-empty value for all requested fields, as defined by the fields parameter (see above).

    Example usage (value): true

Example (Python):

>>> import requests
>>> import json
>>> data = {
    'fields': ['price', 'bathrooms'],
    'force_fields': True
}
>>> r = requests.post('http://localhost:5000/api/allListings', json=data)
>>> r.json()
[{'bathrooms': 1.0, 'price': 60.0},
 {'bathrooms': 1.0, 'price': 90.0},
 {'bathrooms': 1.0, 'price': 28.0},
 {'bathrooms': 1.0, 'price': 125.0},
 ...
]

filterListings

This method is used to retrieve filtered listings. Additionally, the retrieved attributes per listing can be filtered (similar as for allListings). For this purpose, the method implements the POST HTTP method. To use this method, provide the request as JSON object. The following parameters/keys are relevant in this matter:

  • criteria JSON object required

    Each key in this parameter represents a single filter criterium. The allowed filtering criteria are listed below.

    • price JSON array numeric range
    • bedrooms JSON array numeric range
    • bathrooms JSON array numeric range
    • accommodates JSON array numeric range
    • property_type JSON array string value
    • room_type JSON array string value
    • neighbourhood JSON array string value

    Note that none of the above filter criteria are required. However, two different types are defined:

    • numeric range

      This type represents - as the name suggests - a numeric range. The JSON array needs to be of length two. The first position in the array corresponds to the lower bound (inclusive) and the second position to the upper pound (inclusive). This type is implemented for numeric attributes such as the price or number of bathrooms.

    • string value

      This type is meant for non-numeric attributes, i.e. where filtering can only be done based on equality. Note that the criteria above (denoted with string value) are also represented by a JSON array, i.e. it is possible to filter for multiple string values. For example, it would be possible to filter for listings of different neighbourhoods.

    Criteria with type JSON array are, in fact, meant to represent a numeric range. Consequently, the JSON array should consist of two integers. The first position denotes the lower bound (including) and the second position corresponds to the upper bound (including).

  • fields JSON array optional

    Have a look here for more details.

  • force_fields booleanoptional

    Have a look here for more details.

The request response is always a JSON array of objects. Two HTML codes are important for this method:

  • 200: Everything was okay.
  • 400: Oops, something went wrong. Check the error message and make sure data is correctly submitted.

Example (Python):

>>> import requests
>>> data = {
    'criteria': {'price': [100, 200], 'neighbourhood': ['Mitte']},
    'fields': ['name', 'price', 'neighbourhood']
}
>>> r = requests.post('http://localhost:5000/api/filterListings', json=data)
>>> r.json()
[{'name': 'Prenzel garden with leafy terrace (quiet Guests)',
  'neighbourhood': 'Mitte',
  'price': 160.0},
 {'name': 'Rooftop apt. w/ great view, 2 bedrooms,2 bathrooms',
  'neighbourhood': 'Mitte',
  'price': 150.0},
 ...
]

pricePrediction

This method can be used to get a price estimation for a not yet listed apartment. Request can be made with HTTP POST. The following parameters must be submitted as JSON object with the following keys:

  • bathrooms integer required

    Number of bathrooms in the apartment.

  • bedrooms integer required

    Number of bedrooms in the apartment.

  • accommodates integer required

    Number of accommodates the apartment has room for.

  • guest_included integer required

    Number of guests included in the price.

  • gym binary required

    Whether the apartment offers a gym.

  • ac binary required

    Whether there's air conditioning in the apartment.

  • elevator binary required

    Whether there is an elevator in the apartment building.

  • neighbourhood string required

    Name of the neighbourhood.

  • property_type string required

    Type of the property.

  • room_type string required

    Type of the room.

The response is a JSON object. The object contains a key prediction whose value represents the predicted price. Two HTML codes are important for this method:

  • 200: Everything was okay.
  • 400: Oops, something went wrong. Check the error message and make sure data is correctly submitted.

Example (Python):

>>> import requests
>>> data = {
    'bathrooms': 1,
    'bedrooms': 2,
    'accommodates': 2,
    'guests_included': 1,
    'gym': 0,
    'ac': 1,
    'elevator': 1,
    'neighbourhood': 'Mitte',
    'property_type': 'House',
    'room_type': 'Private Room'
}
>>> r = requests.post('http://localhost:5000/api/pricePrediction', data=data)
>>> r.json()
{"price": "16.7165146"}

pricePredictionParamValues

This method can be used to retrieve the valid values for the parameters of the pricePrediction method. Request can only be made with HTTP GET.

The response is a JSON object. Each key in the response object corresponds to a parameter in a pricePrediction request. The keys' values are, again, JSON objects with two keys: type and values. values is always a JSON array, however, type defines how to interpret values:

  • num

    In this case, values represents a numeric range. values contains two elements, where the first element corresponds to the lower bound of the range (inclusive) and the second element to the upper bound (inclusive).

  • binary

    In this case, the values in values represents the valid values for the corresponding parameter.

  • string

    In this case, the values in values represents the valid values for the corresponding parameter.

The request response is always a JSON object. Two HTML codes are important for this method:

  • 200: Everything was okay.
  • 400: Oops, something went wrong. Check the error message and make sure data is correctly submitted.

Example (Python):

>>> import requests
>>> r = requests.get('http://localhost:5000/api/pricePredictionParamValues')
>>> r.json()
{'bathrooms': {'type': 'num', 'values': [0, 100]},
 'bedrooms': {'type': 'num', 'values': [0, 100]},
 'accommodates': {'type': 'num', 'values': [0, 100]},
 'guests_included': {'type': 'num', 'values': [0, 100]},
 'gym': {'type': 'binary', 'values': [true, false]},
 'ac': {'type': 'binary', 'values': [true, false]},
 'elevator': {'type': 'binary', 'values': [true, false]},
 'neighbourhood': {'type': 'string',
  'values': ['Adlershof',
   'Albrechtstr.',
   ...
  ]
 },
 ...
}

avgPricePerNeighbourhood

This method can be used to get the average price per neighbourhood. Additionally, the geojson data for a neighbourhood is returned, as well. The method implements two HTTP methods: GET and POST. The GET method does not apply any pre-filtering (before aggregating listings per neighbourhood), while the POST method allows to apply such filtering, similarly filterListings. In any case, a JSON object with the following keys is returned:

  • avgPrice float

    The average price of the neighbourhood (in $).

  • relAvgPrice float

    A relative value in the range [0, 1], where the value for the neighbourhood with the highest absolute average price is set to 1.

  • neighbourhood string

    The name of the neighbourhood.

  • geometry object

    A geojson object for the corresponding returned neighbourhood.

Whether a GET or POST request is made, the request response is always a JSON array of objects. Two HTML codes are important for this method:

  • 200: Everything was okay.
  • 400: Oops, something went wrong. Check the error message and make sure data is correctly submitted.

GET method

Example (Python):

>>> import requests
>>> r = requests.get('http://localhost:5000/api/avgPricePerNeighbourhood')
>>> r.json()
[{'avgPrice': 43.476190476190474,
  'neighbourhood': 'Köpenick-Süd',
  'relAvgPrice': 0.12825871508433642,
  'geometry': {'type': 'MultiPolygon',
   'coordinates': [[[[13.572964, 52.438657],
   ...]]]
 },
 ...
]

POST method

As stated above, the POST method allows to apply a pre-filtering. It follows the same principle as for the filterListings methods, however, only the criteria parameter is allowed. For a detailed explanation of this parameter, please have a look a the mentioned (method)[https://github.com/webuko/backend/wiki/API-Documentation/_edit#filterlistings].

Example (Python):

>>> import requests
>>> data = {
    'criteria': {
        'bedrooms': [2, 5]
    }
}
>>> r = requests.post('http://localhost:5000/api/avgPricePerNeighbourhood')
>>> r.json
[{'avgPrice': 43.476190476190474,
  'neighbourhood': 'Köpenick-Süd',
  'relAvgPrice': 0.12825871508433642,
  'geometry': {'type': 'MultiPolygon',
   'coordinates': [[[[13.572964, 52.438657],
   ...]]]
  },
  ...
]
Clone this wiki locally