PyTools

PyTools is a Python library that provides a wrapper for CostQuest APIs. CostQuest encourages the use of the library to make using the APIs easier and to prevent inefficient credit usage by custom implementations. If you choose to interface directly with the REST APIs, carefully review your code and consider using the PyTools library as a model for best practices.

GitHub Repository

Examples

PyTools makes it very easy to perform common operations such as acquiring Fabric data, address matching, and geolocating existing data into the Fabric.

Data Pull

This shows a custom data pull for a KMZ file for datalevel=20. The fieldnames array controls the order of fields for the CSV export.

from cqazapipytools import *
with cqazapipytools(os.environ['CQAPIKEY']) as cp:
    geojson = cp.convert('/mnt/c/Temp/data.kmz')
    collect = cp.collect('202412',geojson)
    attach = cp.attach('202412',collect,datalevel=20)
    cp.csvWrite('demo_data_output.csv', attach, fieldnames=cp.getFields('202412','locations',20,True))

Address Matching 

from cqazapipytools import *
with cqazapipytools(os.environ['CQAPIKEY'], cachepath='cache_match.db') as cp:
    addresses = cp.csvRead('demo_match_input.csv')
    match = cp.match('202506',addresses)
    cp.csvWrite('demo_match_output.csv',match)

Locate Coordinates 

from cqazapipytools import *
with cqazapipytools(os.environ['CQAPIKEY'], cachepath='cache_locate.db') as cp:
    coordinates = cp.csvRead('demo_locate_input.csv')
    locate = cp.locate('202506', coordinates)
    locate = cp.transformList(locate, 'rename', {'latitude':'source_latitude','longitude':'source_longitude'})
    cp.csvWrite('demo_locate_output.csv', cp.mergeList(locate, coordinates, 'sourcekey'))

Coverage Pull 

from cqazapipytools import *
with cqazapipytools(os.environ['CQAPIKEY'], cachepath='cache.db') as cp:
    geojson = cp.apiAction('geosvc/libgetgeo/tiger/2020/counties?id=01001','GET')
    collect = cp.collect('202412',geojson)
    attach = cp.attach('202412',in_list=collect,fields=['location_id'])
    coverage = cp.bulkApiAction('coverage/bdcfixed?vintage=202412', 'POST', [a['location_id'] for a in attach], 1000)
    cp.csvWrite('demo_coverage_output.csv', coverage)

Please reference the GitHub repository for additional information.

Benefits

Using the PyTools library helps solve many challenges that developers may face when utilizing CostQuest APIs.

  • Released under a permissive MIT license. Free to use for all who access CostQuest APIs.
  • Implements automatic retries for request failures as well as adaptive rate limiting. Makes processes more reliable.
  • Supports a local cache database. In the event the same requests to the API are repeated, the cache will be used rather than consuming credits to make new remote requests. This is very useful when designing a process so as not to incur charges for troubleshooting, debugging, and testing.
  • Provides optimization for credit usage. When using PyTools, it will optimize for credit usage. For example, when attaching Fabric data to locations, it will use as few calls to the fabric/bulk API as possible to preserve credits.
  • Implements more complex solutions such as those using the fabricext/locate API. The Locate API restricts requests by geographic area to ensure reasonable processing times. PyTools automatically breaks data up and processes it ensuring the Locate API can be used with a single command rather than rewriting hundreds of lines of code to optimize a solution.
  • For APIs without direct function implementations, there are generic functions for performing single and bulk requests to CostQuest APIs. For example, to obtain a broad region of BDC coverage data via the coverage/bdcfixed API.
  • Helper functions exist to shortcut basic operations such as reading and writing CSV and JSON data, as well as manipulating lists and dicts to more quickly get them in differing formats.
  • Since CostQuest APIs operate solely on GeoJSON for geographic requests, a convert function exists to create valid GeoJSON representations of common geographic formats. This often means there is no need to go into a desktop GIS system to convert existing data into boundaries suitable for use while calling CostQuest APIs.
  • Development of the PyTools library is ongoing, and as it matures, benefits will be available to all who choose to use it.