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

6fd27993df15f7c8a9b2e02a16c6d385

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	1804
1	NPL.3.2.5_1	621
2	NPL.5.1.2_1	178
3	NPL.4.1.1_1	296
4	NPL.1.3.3_1	606

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	1804
1	NPL.3.2.5_1	621
2	NPL.5.1.2_1	178
3	NPL.4.1.1_1	296
4	NPL.1.3.3_1	606

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

afebdbabe9fb05f94f63124997d4502f

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	2075
1	NPL.3.2.5_1	715
2	NPL.5.1.2_1	209
3	NPL.4.1.1_1	345
4	NPL.1.3.3_1	687

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	2075
1	NPL.3.2.5_1	715
2	NPL.5.1.2_1	209
3	NPL.4.1.1_1	345
4	NPL.1.3.3_1	687

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

c592ff8eddefa0cbcac23a22a9747d79

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	906
1	NPL.1_1	NPL.4_1	369
2	NPL.1_1	NPL.3_1	397
3	NPL.1_1	NPL.2_1	1060
4	NPL.1_1	NPL.1_1	9876

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	64
1	NPL.1.1.1_1	2016-01-01	1	63
2	NPL.1.1.1_1	2016-01-01	2	67
3	NPL.1.1.1_1	2016-01-01	3	56
4	NPL.1.1.1_1	2016-01-01	4	59

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¶