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,
               'hours': 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

4780fa5608b1db80407ff42f749dfe81

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.2.1.3_1 704
1 NPL.2.2.4_1 271
2 NPL.1.2.2_1 497
3 NPL.1.3.2_1 1162
4 NPL.5.3.4_1 918

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.2.1.3_1 704
1 NPL.2.2.4_1 271
2 NPL.1.2.2_1 497
3 NPL.1.3.2_1 1162
4 NPL.5.3.4_1 918

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,
                'hours': 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,
                'hours': 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,
                'hours': 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,
                'hours': 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

c52b229f0fd5a8d761436f0becc7b37d

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.2.1.3_1 807
1 NPL.2.2.4_1 323
2 NPL.1.2.2_1 555
3 NPL.1.3.2_1 1349
4 NPL.5.3.4_1 1069

Alternative:

df = flowclient.get_result(
    connection=conn,
    query_spec=flowclient.aggregates.spatial_aggregate_spec(locations=ml),
)
df.head()
pcod value
0 NPL.2.1.3_1 807
1 NPL.2.2.4_1 323
2 NPL.1.2.2_1 555
3 NPL.1.3.2_1 1349
4 NPL.5.3.4_1 1069

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,
                   'hours': None,
                   'mapping_table': None,
                   'method': 'last',
                   'query_kind': 'daily_location',
                   'subscriber_subset': None},
 'join_type': 'inner',
 'query_kind': 'flows',
 'to_location': {'aggregation_unit': 'admin1',
                 'date': '2016-01-07',
                 'event_types': None,
                 'geom_table': None,
                 'geom_table_join_column': None,
                 'hours': 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

2ce674e16b51d49a49828fa025ad8a6f

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 719
1 NPL.1_1 NPL.4_1 634
2 NPL.1_1 NPL.3_1 444
3 NPL.1_1 NPL.2_1 1126
4 NPL.1_1 NPL.1_1 11557

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 53
1 NPL.1.1.1_1 2016-01-01 1 56
2 NPL.1.1.1_1 2016-01-01 2 65
3 NPL.1.1.1_1 2016-01-01 3 51
4 NPL.1.1.1_1 2016-01-01 4 73