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

6d3560682a12cd12059981e6ec085338

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.2_1	252
1	NPL.3.2.2_1	593
2	NPL.1.2.6_1	1428
3	NPL.2.1.4_1	378
4	NPL.4.1.5_1	184

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.2_1	252
1	NPL.3.2.2_1	593
2	NPL.1.2.6_1	1428
3	NPL.2.1.4_1	378
4	NPL.4.1.5_1	184

Modal location

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

4c3ea5c829f6579bb685ef8f38fb717d

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.2_1	282
1	NPL.3.2.2_1	654
2	NPL.1.2.6_1	1631
3	NPL.2.1.4_1	455
4	NPL.4.1.5_1	219

Alternative:

df = flowclient.get_result(
    connection=conn,
    query_spec=flowclient.aggregates.spatial_aggregate_spec(locations=ml),
)
df.head()

	pcod	value
0	NPL.2.1.2_1	282
1	NPL.3.2.2_1	654
2	NPL.1.2.6_1	1631
3	NPL.2.1.4_1	455
4	NPL.4.1.5_1	219

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

57cd7978fab584e8d3f21987a1af0b96

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	695
1	NPL.1_1	NPL.4_1	492
2	NPL.1_1	NPL.3_1	644
3	NPL.1_1	NPL.2_1	1095
4	NPL.1_1	NPL.1_1	12284

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.2_1	2016-01-01	0	83
1	NPL.1.1.2_1	2016-01-01	1	57
2	NPL.1.1.2_1	2016-01-01	2	77
3	NPL.1.1.2_1	2016-01-01	3	79
4	NPL.1.1.2_1	2016-01-01	4	77