API Reference

class obplatform.Connector(endpoint='https://api.ashraeobdatabase.com')[source]

Bases: object

Connector to the remote database

Initialize the connector

Parameters: endpoint (str) – The endpoint of the remote database, currently this should be “https://api.ashraeobdatabase.com”

__init__(endpoint='https://api.ashraeobdatabase.com')[source]

Initialize the connector

Parameters: endpoint (str) – The endpoint of the remote database, currently this should be “https://api.ashraeobdatabase.com”

list_behaviors()[source]

Lists all behaviors available in the database

Return type

List[Dict[str, Any]]

Returns

List of dicts showing all behaviors in the database. The “key” field is what users should use to query and download the data. The “label” field is what is displayed to users on the website

For example, {“label”: “Occupant Presence”, “key”: “Occupancy”, “disabled”: false} “Occupant Presence” is the behavior name shown on the website, “Occupancy” is what users should use in API and other functions in this module to query and download the data from the database.

download_export(filename, behavior_ids, studies, show_progress_bar=False, chunk_size=1024000)[source]

Download the data archive (ZIP) for the given behaviors

Parameters

filename (str) – The filename to save the archive
behavior_ids (List[int | str]) – List of behavior ids to download
studies (List[int | str]) – List of study ids to download
show_progress_bar (bool) – Whether to show a progress bar
chunk_size (Optional[int]) – The size of each chunk to download. If None, download the whole file. Default is 1000 * 1024 Bytes.

Return type

None

check_health()[source]

Check the health of the remote database

Return type: bool
Returns: True if the backend server is working, False otherwise

list_behaviors_in_studies(studies)[source]

List available behaviors in each study

Parameters: studies (int | str) – List of study ids to query
Return type: List[Dict[str, Any]]
Returns: JSON encoded result of study id and behaviors in the study

list_studies(behaviors, countries, cities, buildings)[source]

Query available studies based on behaviors, countries, cities and buildings. This function works in the same way as clicking through the “Export” page on the website.

Parameters

behaviors (List[int | str]) – List of behavior ids to query
countries (List[str]) – List of country names to query
cities (List[str]) – List of city names to query

buildings (List[Dict[str, Any]]) –

List of building types and room types to query. Must be in the following format:

[
    {
        "building_type": "Educational",
        "room_type": "Classroom",
    },
    {
        "building_type": "Educational",
        "room_type": "Office",
    },
    {
        "building_type": "Residential",
        "room_type": "Single-Family House",
    },
]

Return type

List[Dict[str, Any]]

Returns

JSON encoded result of study ids available in the database filtered by the criteria.