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

e20a22121e18d216da6b239d4614a636

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.3.3_1 321
1 NPL.3.2.5_1 1151
2 NPL.4.1.1_1 517
3 NPL.1.3.3_1 307
4 NPL.1.1.3_1 5640

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.3.3_1 321
1 NPL.3.2.5_1 1151
2 NPL.4.1.1_1 517
3 NPL.1.3.3_1 307
4 NPL.1.1.3_1 5640

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

b75ca38dfdee47c88d13b72abdd4aab3

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.3.3_1 381
1 NPL.3.2.5_1 1320
2 NPL.1.3.3_1 355
3 NPL.4.1.1_1 614
4 NPL.1.1.3_1 6446

Alternative:

df = flowclient.get_result(
    connection=conn,
    query_spec=flowclient.aggregates.spatial_aggregate_spec(locations=ml),
)
df.head()
pcod value
0 NPL.2.3.3_1 381
1 NPL.3.2.5_1 1320
2 NPL.1.3.3_1 355
3 NPL.4.1.1_1 614
4 NPL.1.1.3_1 6446

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

206b5c4ea5741699e84f340329faa319

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 924
1 NPL.1_1 NPL.4_1 604
2 NPL.1_1 NPL.3_1 387
3 NPL.1_1 NPL.2_1 1037
4 NPL.1_1 NPL.1_1 11750

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 22
1 NPL.1.1.1_1 2016-01-01 1 28
2 NPL.1.1.1_1 2016-01-01 2 29
3 NPL.1.1.1_1 2016-01-01 3 20
4 NPL.1.1.1_1 2016-01-01 4 26