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

6e5ce5de4b29eb81b7b9fc68de6928e2

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	1410
1	NPL.3.2.5_1	1492
2	NPL.1.3.3_1	263
3	NPL.4.1.1_1	1068
4	NPL.1.1.3_1	5030

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	1410
1	NPL.3.2.5_1	1492
2	NPL.1.3.3_1	263
3	NPL.4.1.1_1	1068
4	NPL.1.1.3_1	5030

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

d349286bab3ad0db58525b085ecb8058

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	1626
1	NPL.3.2.5_1	1700
2	NPL.1.3.3_1	312
3	NPL.4.1.1_1	1189
4	NPL.1.1.3_1	5640

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	1626
1	NPL.3.2.5_1	1700
2	NPL.1.3.3_1	312
3	NPL.4.1.1_1	1189
4	NPL.1.1.3_1	5640

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

d001368334be05c75d603214a6bf9374

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	678
1	NPL.1_1	NPL.4_1	502
2	NPL.1_1	NPL.3_1	509
3	NPL.1_1	NPL.2_1	1090
4	NPL.1_1	NPL.1_1	9752

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	42
1	NPL.1.1.1_1	2016-01-01	1	42
2	NPL.1.1.1_1	2016-01-01	2	38
3	NPL.1.1.1_1	2016-01-01	3	39
4	NPL.1.1.1_1	2016-01-01	4	53

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¶