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

8cd12ba2ba51ed7cfc170414cdebe774

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	1364
1	NPL.3.2.5_1	1287
2	NPL.1.3.3_1	865
3	NPL.4.1.1_1	815
4	NPL.1.1.3_1	6898

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	1364
1	NPL.3.2.5_1	1287
2	NPL.1.3.3_1	865
3	NPL.4.1.1_1	815
4	NPL.1.1.3_1	6898

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

cda4adf3c90ab547714739e70f3b0ce8

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	1567
1	NPL.3.2.5_1	1447
2	NPL.4.1.1_1	928
3	NPL.1.3.3_1	990
4	NPL.1.1.3_1	7857

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	1567
1	NPL.3.2.5_1	1447
2	NPL.4.1.1_1	928
3	NPL.1.3.3_1	990
4	NPL.1.1.3_1	7857

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

10b2059c7e907350571ef4bc7dd71932

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	1081
1	NPL.1_1	NPL.4_1	552
2	NPL.1_1	NPL.3_1	556
3	NPL.1_1	NPL.2_1	809
4	NPL.1_1	NPL.1_1	11965

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	35
1	NPL.1.1.1_1	2016-01-01	1	48
2	NPL.1.1.1_1	2016-01-01	2	35
3	NPL.1.1.1_1	2016-01-01	3	52
4	NPL.1.1.1_1	2016-01-01	4	47

Example usage

Create an access token¶

Create an API connection¶

Daily location¶

Specify query parameters¶

Set query running¶

Check status of query¶

Get query result¶

Modal location¶

Specify query parameters¶

Set query running¶

Check status of query¶

Get query result¶

Flow¶

Specify query parameters¶

Set query running¶

Check status of query¶

Get query result¶

Counts of Events by Location¶