Using the CLI¶

The CityIq module includes two programs that can access a CityIQ system, ciq_events to download events and ciq_nodes to get locations and assets. The package also includes the ciq_config create and dump the config file.

ciq_events: Download events¶

The ciq_events downloads events from the CityIq system and caches the events locally in CSV files, one file per day per event per asset. The ciq_events program can both download the events and, with the -O, write combined CSV files. The -O option will produce a directory of CSV file, with one file for each asset, holding events over the entire date range.

ciq_events¶

Download events and load them into the cache.

The ciq_events program will request events from a CityIQ system, one day at a tim, and cache the results. It will request the events from assets, based on which assets have eventTypes with the requested events.

Because the program will request events for all of the assets that report an event type and makes one request per day, it can generate very large numbers of requests and take many hours to run. For instance this request:

ciq_events -s 2020-01-01 -e 2020-06-01-01 PKIN PKOUT

generates about 800,000 requests and will take a day to run.

The cityiq module will not cache event requests for the current day or any day in the future.

usage: ciq_events [-h] [--version] [-v] [-vv] [-a ASSETS] [-c CONFIG]
                  [-w WORKERS] [-s START_TIME] [-f END_TIME]
                  [-e EVENTS [EVENTS ...]] [-o OUTPUT_NAME] [-O]

-h, --help¶: show this help message and exit

--version¶: show program’s version number and exit

-v, --verbose¶: set loglevel to INFO

-vv, --very-verbose¶: set loglevel to DEBUG

-a <assets>, --assets <assets>¶: Path to a CSV file of assets, of the form produced by the ‘ciq_nodes’ program.

-c <config>, --config <config>¶: Path to configuration file

-w <workers>, --workers <workers>¶: Number of threads to use

-s <start_time>, --start-time <start_time>¶: Starting time, in iso format. If not specified, use the configuration value ‘start_time’

-f <end_time>, --end-time <end_time>¶: Ending time, in iso format. If not specified, end time is yesterday

-e <events>, --events <events>¶: Names of events to scrape. One or more of: PKIN,PKOUT,PEDEVT,TFEVT,BICYCLE

-o <output_name>, --output-name <output_name>¶: Output file, where events are written in CSV format

-O, --output¶: Coalesce data into one CSV file per asset

ciq_nodes: Download assets and locations¶

ciq_nodes¶

Get assets and locations for a CityIQ system

usage: ciq_nodes [-h] [--version] [-v] [-vv] [-C CONFIG] [-c | -j | -l]
                 [-o [OUTPUT]] [-F]
                 [-M ASSET_MAP_CSV | --assets | --nodes | --cameras | --env_sensors | --em_sensors  | --mics | --locations | --walkways | --traffic_lanes | --parking_zones]

-h, --help¶: show this help message and exit

--version¶: show program’s version number and exit

-v, --verbose¶: set loglevel to INFO

-vv, --very-verbose¶: set loglevel to DEBUG

-C <config>, --config <config>¶: Path to configuration file

-c, --csv¶: Write output as CSV.

-j, --json¶: Write output as JSON.

-l, --jsonl¶: Write output as JSON lines.

-o <output>, --output <output>¶: Output file name. If not specified, write to stdout, except for -M, which is always writen to a file.

-F, --no-cache¶: Don’t use cached metadata; force a request to the API

-M <asset_map_csv>, --asset-map-csv <asset_map_csv>¶: Write a CSV file that maps assets to locations

--assets¶: Print all assets as JSON lines

--nodes¶: Print all nodes as JSON lines

--cameras¶: Print all cameras as JSON lines

--env_sensors¶: Print all env_sensors as JSON lines

--em_sensors¶: Print all em_sensors as JSON lines

--mics¶: Print all mics as JSON lines

--locations¶: Print all locations as JSON lines

--walkways¶: Print all walkways as JSON lines

--traffic_lanes¶: Print all traffic_lanes as JSON lines

--parking_zones¶: Print all parking_zones as JSON lines

ciq_config: Manage the configuration file¶

ciq_config¶

Create or print the cityiq module configuration.

You can create a new configuration file with the -w option or print the configuration with -p

usage: ciq_config [-h] [--version] [-w] [-u] [-F] [-p]

-h, --help¶: show this help message and exit

--version¶: show program’s version number and exit

-w, --write¶: Write a new default config file to the current directory, or with -u to the user’s directory

-u, --user¶: With –write, write to the user’s home directory, ~/.cityiq.yaml

-F, --force¶: With –write, force overwritting

-p, --print¶: Print the config file