Filtering

Most resources that support bulk fetches via "list" API methods also have filters available, like the creation date, the name of the resource etc. Filters can be chained, that means multiple filters can be combined using query string parameters like in the first date filter example.

Date filter examples

A lot of resources have a created attribute that records the date of its creation. It can be used to narrow a request down to a certain period of time.

Exact date

To get resources that have been created on Guido van Rossum's birthday

query string

?created__date=1956-01-31

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.simulations_list(
        created__date="1956-01-31"
    )

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/simulations/?created__date=1956-01-31"

Arbitrary time range

To get resources that have been created during the 1988 UEFA European Football Championship you can use the greater than equals filter gte in combination with the less than equals filter lte

query string

?created__date__gte=1988-06-10&created__date__lte=1988-06-25

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.simulations_list(
        created__date__gte="1988-06-10",
        created__date__lte="1988-06-25"
    )

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/simulations/?created__date__gte=1988-06-10&created__date__lte=1988-06-25"

Specific month/year

To get resources that have been created in the month of the Carnation Revolution

query string

?created__year=1974&created__month=04

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.simulations_list(
        created__year="1974", created__month="04"
    )

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/simulations/?created__year=1974&created__month=04"

String filter examples

Most resources have string fields, like a name or slug field. Usually these fields have a set of available filters that can be used to search for a specific resource or set of resources.

To get resources that are named "Mekong".

query string

?name=Mekong

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.simulations_list(
        name="Mekong"
    )

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/simulations/?name=Mekong"

To get resources with a name that contains "Mekong"

query string

?name__contains=Mekong

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.simulations_list(
        name__contains="Mekong"
    )

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/simulations/?name__contains=Mekong"

Case sensitivity

String filters are by default case-sensitive. So ?name=mekong would not a return a result if the name attribute of the resource originally was created with a capital M. For the most important filters there is a case-insensitive variant that can be recognized by the leading i, e.g. icontains

To get resources with a name matching both "Mekong" and "mekong", thus is case insensitive

query string

?name__icontains=Mekong # matches both Mekong and mekong

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    # matches both Mekong and mekong`
    api_client.simulations_list(
        name__icontains="Mekong"
    )

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/simulations/?name__icontains=Mekong"

To get resources with a name that starts with "Monty"

query string

?name__startswith=Monty # does not match monty python

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    # does not match monty python
    api_client.simulations_list(
        name__startswith="Monty"
    )

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/simulations/?name__startswith=Monty"

To turn the search into a case-independent one

query string

?name__istartswith=Monty # both matches Monty Python and monty python

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    # both matches Monty Python and monty python
    api_client.simulations_list(
        name__istartswith="Monty"
    )

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/simulations/?name__istartswith=Monty"

To get resources with a name that ends with "Python"

query string

?name__endswith=Python # does not match monty python

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    # does not match monty python
    api_client.simulations_list(
        name__endswith="Python"
    )

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/simulations/?name__endswith=Python"

Number filter examples

Number filters are

exact
gt
gte
lt
lte
isnull

exact

Matches a number exactly, for instance an exit code

query string

?exit_code=4120

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.statuses_list(exit_code=4120)

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/statuses/?exit_code=4120"

gt

Matches numbers that are greater than, for instance the exit codes greater than 4161

query string

?exit_code__gt=4161 # this won't include 4161 itself

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.statuses_list(exit_code__gt=4161)

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/statuses/?exit_code__gt=4161"

gte

Matches numbers that are greater than or equal, for instance the exit codes greater than or equal to 4161

query string

?exit_code__gte=4161 # this will include 4161

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.statuses_list(exit_code__gte=4161)

curl

curl  --request GET
      --header "Authorization: Bearer <your token here>
      --header  "accept: application/json"
      "https://api.3di.live/v3/statuses/?exit_code__gte=4161"

Special Filters

A few resources allow for special filtering that span complex relationships between resources.

Simulation tags

The simulations tag field is a versatile feature. It makes it easy to group simulations for example. Imagine you are simulating 10 different rain events in Singapore of different intensities. By adding the tags downpour,singapore to each simulation resource you will be able to gather them afterwards by a single request.

query string

?tags__in=downpour # the singapore tag in this case in optional

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    # the singapore tag in this case in optional`
    api_client.simulations_list(
        tags__in="downpour"
    )

curl example

curl --request GET --header "Authorization: Bearer <your token here> --header "accept: application/json" "https://api.3di.live/v3/simulations/?tags__in=downpour"

Imagine your project scope changes and you also have to simulate the same rain events in Kuala Lumpur. Let's stick to the city names and tag the simulation resources you are creating downpour,kuala-lumpur. Now you will be able to retrieve all simulations for your project through the query string parameter ?tags__in=downpour as shown above. To limit the response to simulations for Singapore

query string

?tags__in=singapore

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.simulations_list(
        tags__in="singapore"
    )

curl example

    curl  --request GET
          --header "Authorization: Bearer <your token here>
          --header  "accept: application/json"
          "https://api.3di.live/v3/simulations/?tags__in=singapore"

And To limit the response to simulations for Kuala Lumpur

query string

?tags__in=kuala-lumpur

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    api_client.simulations_list(
        tags__in="kuala-lumpur"
    )

curl example

    curl  --request GET
          --header "Authorization: Bearer <your token here>
          --header  "accept: application/json"
          "https://api.3di.live/v3/simulations/?tags__in=kuala-lumpur"

Simulation statuses

The statuses endpoints defines several filters that make it possible to list status resources for a given user or organisation, though these entities are not defined on the resource itself.

filter by username

Get all status resources for a given user.

?simulation__user__username=black.sheep

filter by organisation name

Here the cas-independent filter istartswith is linked to the organisation name the simulation resource has been created under. To get all status resources for organisations whose name starts with "nelen"

?simulation__organisation__name__istartswith=nelen