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',
               'event_types': None,
               '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

7b316aac55ea423ef52c5607262fdd9a

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 NPL.1.3.3_1 311
1 NPL.4.1.1_1 534
2 NPL.1.1.3_1 2907
3 NPL.3.1.4_1 1344
4 NPL.1.2.1_1 575

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 NPL.1.3.3_1 311
1 NPL.4.1.1_1 534
2 NPL.1.1.3_1 2907
3 NPL.3.1.4_1 1344
4 NPL.1.2.1_1 575

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',
                'event_types': None,
                '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',
                'event_types': None,
                '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',
                'event_types': None,
                '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',
                'event_types': None,
                '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

609c8b454bbad434e0b2609dd2c96371

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 NPL.1.3.3_1 369
1 NPL.4.1.1_1 604
2 NPL.1.1.3_1 3391
3 NPL.3.1.4_1 1560
4 NPL.1.2.1_1 659

Alternative:

df = flowclient.get_result(
    connection=conn, query_spec=flowclient.aggregates.spatial_aggregate_spec(locations=ml)
)
df.head()
pcod value
0 NPL.1.3.3_1 369
1 NPL.4.1.1_1 604
2 NPL.1.1.3_1 3391
3 NPL.3.1.4_1 1560
4 NPL.1.2.1_1 659

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',
                   'event_types': None,
                   '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',
                 'event_types': None,
                 '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

e541a4a96026b1a357c073fb5f9ac3dc

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 NPL.1_1 NPL.5_1 783
1 NPL.1_1 NPL.4_1 389
2 NPL.1_1 NPL.3_1 406
3 NPL.1_1 NPL.2_1 1073
4 NPL.1_1 NPL.1_1 9159

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 NPL.1.1.1_1 2016-01-01 0 67
1 NPL.1.1.2_1 2016-01-01 0 68
2 NPL.1.1.3_1 2016-01-01 0 274
3 NPL.1.2.1_1 2016-01-01 0 52
4 NPL.1.2.3_1 2016-01-01 0 36