API ReferenceData APIHelp CenterCommunityDevice TutorialsSample Projects
LoginSign up

Related

The Filters are that powerful that it's possible to apply filters on related entities.
Whenever you see Related Filter Attribute in the column Attribute Type it's a signal that related filters can be used.

Each entity has a section listing all possible filters per entity. Please note, that not all attributes from the Entity Object have filters.

📘

What is a Related Filter?

A related Filter is basically a filter applied on an (entity) attribute. Sounds weird? It is weird.
Let's see an example:
A Device has an attribute organization as it can be assigned to only one organization. Now remember the filters of Organization.

Hence you can filter for a device and based on filter for a specific field of the organization at the same time. It follows the following scheme: <entity_attribute>__<entity_attribute_filter>.
Practically it means requesting one or more devices, that meet the condition of a specific field. In our case it is the device(s) that are assigned to an organization with a specific name.

🚧

Return Object

Please note, the Related Filters are intended to limit (or filter) the output of that specific endpoint, in other words, if the request is made to api/v2.0/devices/ using a Related Filter variables like this: api/v2.0/devices/?variables__unit=km simply means that request intends to obtain all Devices that contain variables with a synthetic unit. (It does not mean the request obtains the variables that have "synthetic" as unit).

GET  https://industrial.api.ubidots.com/api/v2.0/devices/?organization__name=organization_name

//Returns Array 'results' with devices that are assigned to 'organization_name'

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "organization": {
                "url": "https://industrial.api.ubidots.com/api/v2.0/organizations/5e5427ea1d84725ac9d80f8d",
                "_deprecated_id": 49886,
                "id": "5e5427ea1d84725ac9d80f8d",
                "label": "organization_name",
                "name": "organization_name"
            },
            ...
        },
        {
            "organization": {
                "url": "https://industrial.api.ubidots.com/api/v2.0/organizations/5e5427ea1d84725ac9d80f8d",
                "_deprecated_id": 49886,
                "id": "5e5427ea1d84725ac9d80f8d",
                "label": "organization_name",
                "name": "organization_name"
            },...
        }
    ]
}

The same principle can be applied to other variable type, such as Booleans, Texts, or Numbers.

GET https://industrial.api.ubidots.com/api/v2.0/devices/?organization__name__startswith=comp

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "organization": {
                "url": "https://industrial.api.ubidots.com/api/v2.0/organizations/5e5427ea1d84725ac9d80f8d",
                "_deprecated_id": 49886,
                "id": "5e5427ea1d84725ac9d80f8d",
                "label": "company_1",
                "name": "company_1"
            },
            ...
        },
        {
            "organization": {
                "url": "https://industrial.api.ubidots.com/api/v2.0/organizations/5e5427ea1d84725ac9d80f8d",
                "_deprecated_id": 49886,
                "id": "5e5427ea1d84725ac9d80f8d",
                "label": "company_2",
                "name": "company_2"
            },
            ...
        }
    ]
}