Skip to content

Example usage

Example usage of FlowClient to run daily location, modal location and flow queries.

import flowclient

Create an access token

Generate an API access token using FlowAuth.

Create an API connection

Paste the access token from FlowAuth here as TOKEN

conn = flowclient.connect(
    url=os.getenv("FLOWAPI_URL", "http://localhost:9090"),
    token=TOKEN,
    ssl_certificate=os.getenv("SSL_CERTIFICATE_FILE"),
)

Daily location

Specify query parameters

query_spec = flowclient.aggregates.spatial_aggregate_spec(
    locations=flowclient.daily_location_spec(
        date="2016-01-01",
        aggregation_unit="admin3",
        method="last",
        subscriber_subset=None,
    )
)

query_spec
{'locations': {'aggregation_unit': 'admin3',
               'date': '2016-01-01',
               'geom_table': None,
               'geom_table_join_column': None,
               'mapping_table': None,
               'method': 'last',
               'query_kind': 'daily_location',
               'subscriber_subset': None},
 'query_kind': 'spatial_aggregate'}

Set query running

query_id = flowclient.run_query(connection=conn, query_spec=query_spec)
query_id

13fd6500c9920b303397f4dd67af5b14

Check status of query

flowclient.get_status(connection=conn, query_id=query_id)

executing

Get query result

df = flowclient.get_result_by_query_id(connection=conn, query_id=query_id)
df.head()

pcod value
0 524 4 11 60 636
1 524 3 09 50 29
2 524 1 03 11 1273
3 524 1 03 14 671
4 524 3 07 36 1841

Alternative (run query, wait for it to finish, and get result, in one function call):

df = flowclient.get_result(connection=conn, query_spec=query_spec)
df.head()
pcod value
0 524 4 11 60 636
1 524 3 09 50 29
2 524 1 03 11 1273
3 524 1 03 14 671
4 524 3 07 36 1841

Specify query parameters

Either explicitly from a set of daily locations:

dl1 = flowclient.daily_location_spec(
    date="2016-01-01",
    aggregation_unit="admin3",
    method="last",
    subscriber_subset=None,
)
dl2 = flowclient.daily_location_spec(
    date="2016-01-02",
    aggregation_unit="admin3",
    method="last",
    subscriber_subset=None,
)
ml = flowclient.modal_location_spec(locations=[dl1, dl2])

ml
{'locations': [{'aggregation_unit': 'admin3',
                'date': '2016-01-01',
                'geom_table': None,
                'geom_table_join_column': None,
                'mapping_table': None,
                'method': 'last',
                'query_kind': 'daily_location',
                'subscriber_subset': None},
               {'aggregation_unit': 'admin3',
                'date': '2016-01-02',
                'geom_table': None,
                'geom_table_join_column': None,
                'mapping_table': None,
                'method': 'last',
                'query_kind': 'daily_location',
                'subscriber_subset': None}],
 'query_kind': 'modal_location'}

Or from a date range:

ml = flowclient.modal_location_from_dates_spec(
    start_date="2016-01-01",
    end_date="2016-01-03",
    aggregation_unit="admin3",
    method="last",
    subscriber_subset=None,
)

ml
{'locations': [{'aggregation_unit': 'admin3',
                'date': '2016-01-01',
                'geom_table': None,
                'geom_table_join_column': None,
                'mapping_table': None,
                'method': 'last',
                'query_kind': 'daily_location',
                'subscriber_subset': None},
               {'aggregation_unit': 'admin3',
                'date': '2016-01-02',
                'geom_table': None,
                'geom_table_join_column': None,
                'mapping_table': None,
                'method': 'last',
                'query_kind': 'daily_location',
                'subscriber_subset': None}],
 'query_kind': 'modal_location'}

Set query running

query_id = flowclient.run_query(
    connection=conn, query_spec=flowclient.aggregates.spatial_aggregate_spec(locations=ml)
)
query_id

ce19502397b1e2b7b1bd16dda1dfde8d

Check status of query

flowclient.get_status(connection=conn, query_id=query_id)

executing

Get query result

df = flowclient.get_result_by_query_id(connection=conn, query_id=query_id)
df.head()

pcod value
0 524 4 11 60 718
1 524 3 09 50 38
2 524 1 03 11 1473
3 524 1 03 14 769
4 524 3 07 36 2143

Alternative:

df = flowclient.get_result(
    connection=conn, query_spec=flowclient.aggregates.spatial_aggregate_spec(locations=ml)
)
df.head()
pcod value
0 524 4 11 60 718
1 524 3 09 50 38
2 524 1 03 11 1473
3 524 1 03 14 769
4 524 3 07 36 2143

Flow

Specify query parameters

Specify parameters for two location queries:

aggregation_unit = "admin1"
dl_past = flowclient.daily_location_spec(
    date="2016-01-01",
    aggregation_unit=aggregation_unit,
    method="last",
    subscriber_subset=None,
)
dl_present = flowclient.daily_location_spec(
    date="2016-01-07",
    aggregation_unit=aggregation_unit,
    method="last",
    subscriber_subset=None,
)

Specify parameters for flow query:

flow = flowclient.aggregates.flows_spec(
    from_location=dl_past,
    to_location=dl_present,
)
flow
{'from_location': {'aggregation_unit': 'admin1',
                   'date': '2016-01-01',
                   'geom_table': None,
                   'geom_table_join_column': None,
                   'mapping_table': None,
                   'method': 'last',
                   'query_kind': 'daily_location',
                   'subscriber_subset': None},
 'query_kind': 'flows',
 'to_location': {'aggregation_unit': 'admin1',
                 'date': '2016-01-07',
                 'geom_table': None,
                 'geom_table_join_column': None,
                 'mapping_table': None,
                 'method': 'last',
                 'query_kind': 'daily_location',
                 'subscriber_subset': None}}

Set query running

query_id = flowclient.run_query(connection=conn, query_spec=flow)
query_id

8b126238065d16ce33809cf5b0c069ff

Check status of query

flowclient.get_status(connection=conn, query_id=query_id)

executing

Get query result

df = flowclient.get_result_by_query_id(connection=conn, query_id=query_id)
df.head()

pcod_from pcod_to value
0 524 1 524 5 302
1 524 1 524 4 709
2 524 1 524 3 553
3 524 1 524 2 459
4 524 1 524 1 6081

Counts of Events by Location

df = flowclient.get_result(
    connection=conn,
    query_spec=flowclient.aggregates.location_event_counts_spec(
        start_date="2016-01-01",
        end_date="2016-01-08",
        aggregation_unit="admin3",
        count_interval="hour",
    ),
)
df.head()

pcod date hour value
0 524 1 01 01 2016-01-01 0 73
1 524 1 01 03 2016-01-01 0 62
2 524 1 01 04 2016-01-01 0 123
3 524 1 02 06 2016-01-01 0 64
4 524 1 02 07 2016-01-01 0 52