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 devices based on 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"
            },
            ...
        }
    ]
}