TargetSmart Developer API

TargetSmart provides access to voter and consumer data for the progressive community.

Overview

The TargetSmartAPI class provides methods to consume the data services provided by the TargetSmart Developer API. Parsons provides the following methods as convenient wrappers for interacting with the corresponding TargetSmart HTTP services:

data_enhance: Quickly retrieve voter and consumer data enrichment fields from TargetSmart’s platform database for a previously identified individual.
radius_search: Search for individuals within a user specified geographic area defined by a radius centered around a latitude/longitude point.
phone: Enrich a list of phone numbers with TargetSmart data
district: Retrieve political district data using one of several lookup options
voter_registration_check: Search TargetSmart’s service database of registered voters, to check if a voter is registered at a given address.
smartmatch: Match CSV file records to TargetSmart’s service database of voting age individuals. Multiple matching strategies are applied to find accurate matches and return enriched data. Read more about SmartMatch, TargetSmart’s list matching solution.

Some TargetSmart API services have not yet been implemented in Parsons. For more information, see the API documentation.

Authentication

Log in to My TargetSmart to access authentication credentials. You will need an API key to use the TargetSmartAPI class.

Note

Endpoint Access: Access to endpoints is individually provisioned. If you encounter errors accessing an endpoint, please contact TargetSmart Client Services to verify that your API key has been provisioned access.

Data Enrichment

Most TargetSmart API services append a set of enrichment data fields as part of a matching or search request. The presence of these fields are provisioned by the TargetSmart Client Services team. Please contact TargetSmart Client Services to learn more or request adjustments.

Quickstart

To instantiate TargetSmartAPI, you can either store your API Key as the environmental variable TS_API_KEY, or pass it in as an argument:

from parsons import TargetSmartAPI

# First approach: Store API key as an environmental variable
ts_api = TargetSmartAPI()

# Second approach: Pass API key as an argument
ts_api = TargetSmartAPI(api_key='my_api_key')

You can then call various methods that correspond to TargetSmart endpoints:

# Search for a person record using an email address
ts_api.data_enhance(search_id='test@email.com', search_id_type='email')

# Search for district information using an address
ts_api.district(search_type='address', address='123 test st, Durham NC 27708')

API

class parsons.TargetSmartAPI(api_key=None)[source]

data_enhance(search_id, search_id_type='voterbase', state=None)

Searches for a record based on an id or phone or email address

Args:

search_id: str: The primary key or email address or phone number
search_id_type: str: One of voterbase, exacttrack, phone, email, smartvan, votebuilder, voter, household.
state: str: Two character state code. Required if search_id_type of smartvan, votebuilder or voter.

Returns

Parsons Table: See Parsons Table for output options.

district(search_type='zip', address=None, zip5=None, zip4=None, state=None, latitude=None, longitude=None)

Return district information based on a geographic point. The method allows you to search based on the following:

Search Type	`search_type`	Required kwarg(s)
Zip Code	`zip`	`zip5`, `zip4`
Address	`address`	`address`
Point	`point`	`latitude`, `longitude`

Args:

search_type: str: The type of district search to perform. One of zip, address or point.
address: str: An uparsed full address
zip5: str: The USPS Zip5 code
zip4: str: The USPS Zip4 code
state: str: The two character state code
latitude: float or str: Valid latitude floating point
longitude: float or str: Valid longitude floating point

Returns:

Parsons Table: See Parsons Table for output options.

phone(table)

Match based on a list of 500 phones numbers. Table can contain up to 500 phone numbers to match

Args:

table: parsons table: See Parsons Table. One row per phone number, up to 500 phone numbers.

Returns:

See Parsons Table for output options.

radius_search(first_name, last_name, middle_name=None, name_suffix=None, latitude=None, longitude=None, address=None, radius_size=10, radius_unit='miles', max_results=10, gender='a', age_min=None, age_max=None, composite_score_min=1, composite_score_max=100, last_name_exact=True, last_name_is_prefix=False, last_name_prefix_length=10, address_type='reg')

Search for a person based on a specified radius

Args:

first_name: str: One or more alpha characters. Required
last_name: str: One or more alpha characters. Required
middle_name: str: One or more alpha characters
name_suffix: str: One or more alpha characters
latitude: float: Floating point number (e.g. 33.738987255507)
longitude: float: Floating point number (e.g. -116.40833849559)
address: str: Any geocode-able address
address_type: str: reg for registration (default) or tsmart for TargetSmart
radius_size: int: A positive integer where combined with radius_unit does not exceed 120 miles
radius_unit: str: One of meters, feet, miles (default), or kilometers.
max_results: int: Default of 10. An integer in range [0 - 100]
gender: str: Default of a. One of m, f, u, a.
age_min: int: A positive integer
age_max: int: A positive integer
composite_score_min: int: An integer in range [1 - 100]. Filter out results with composite score less than this value.
composite_score_max: int: An integer in range [1 - 100]. Filter out results with composite score greater than this value.
last_name_exact: boolean: By default, the full last name is used for finding matches if the length of the last name is not longer than 10 characters. As an example, “anders” is less likely to match to “anderson” with this enabled. Disable this option if you are using either last_name_is_prefix or last_name_prefix_length.
last_name_is_prefix: boolean: By default, the full last name is used for finding matches. Enable this parameter if your search last name is truncated. This can be common for some client applications that for various reasons do not have full last names. Use this parameter along with last_name_prefix_length to configure the length of the last name prefix. This parameter is ignored if last_name_exact is enabled.
last_name_prefix_length: int: By default, up to the first 10 characters of the search last name are used for finding relative matches. This value must be between 3 and 10. This parameter is ignored if last_name_exact is enabled.

Returns

Parsons Table: See Parsons Table for output options.

smartmatch(input_table, max_matches=1, include_email=False, include_landline=False, include_wireless=False, include_voip=False, tmp_location=None, keep_smartmatch_input_file=False, keep_smartmatch_output_gz_file=False)

Submit the contact list records available in the Parsons table input_table to TargetSmart SmartMatch.

Your application provides a contact list which will be matched to TargetSmart’s database of voting age individuals.

TargetSmart Client Services provisions SmartMatch for your API key, configuring the fields from the TargetSmart Data Dictionary that will be appended to each matched record.

This method blocks until TargetSmart has completed the remote workflow execution. The execution time can take minutes to hours to complete depending on the file size, the types of field identifiers present, and TargetSmart system load. SmartMatch executions cannot be canceled once submitted to TargetSmart.

Since Parsons Petl tables are lazy, the SmartMatch output file is always retained in tmp_location. If your Parsons-based ETL workflow fails downstream it may be beneficial to recover the raw SmartMatch output from this location. You may delete this data when it is no longer needed.

Args:

input_table: Parsons or Petl table: A Parsons table with header field names supported by SmartMatch. Required.
max_matches: int: By default only a single best match is returned for an input record. Increase to return additional potentially accurate matches for each input record. Value between 1-10. Default of 1.
include_email: bool: Set to True to include appended email values for matched records. This is only applicable if your TargetSmart account is configued to return email data. Additional charges may apply if True. Default of False.
include_landline: bool: Set to True to include appended landline phone number values for matched records. This is only applicable if your TargetSmart account is configued to return landline phone data. Additional charges may apply if True. Default of False.
include_wireless: bool: Set to True to include appended wireless phone number values for matched records. This is only applicable if your TargetSmart account is configued to return wireless phone data. Additional charges may apply if True. Default of False.
include_voip: bool: Set to True to include appended VOIP phone number values for matched records. This is only applicable if your TargetSmart account is configued to return VOIP phone data. Additional charges may apply if True. Default of False.
tmp_location: str: Optionally provide a local directory path where input/output CSV files will be stored. Useful to recover CSV output if downstream ETL processing fails. If not specified, a system tmp location is used. Default of None.
keep_smartmatch_input_file: bool: Optionally keep the CSV input file that is uploaded in tmp_location for later use. Default of False.
keep_smartmatch_output_gz_file: bool: Optionally keep the gzip compressed output file in tmp_location for later use. The uncompressed output file is always retained in tmp_location. Default of False

Returns:

Parsons Table: A Parsons table wrapping the SmartMatch execution output file records. Each record will include the input record fields followed by columns named tsmart_match_code, a match indicator, vb.voterbase_id, and zero or more additional data element fields based on your TargetSmart account configuration. See Parsons Table for output options.

voter_registration_check(first_name=None, last_name=None, state=None, street_number=None, street_name=None, city=None, zip_code=None, age=None, dob=None, phone=None, email=None, unparsed_full_address=None)

Searches for a registered individual, returns matches.

A search must include the at minimum first name, last name and state.

Args:

first_name: str: Required; One or more alpha characters. Trailing wildcard allowed
last_name: str: Required; One or more alpha characters. Trailing wildcard allowed
state: str: Required; Two character state code (e.g. NY)
street_number: str: Optional; One or more alpha characters. Trailing wildcard allowed
street_name: str: Optional; One or more alpha characters. Trailing wildcard allowed
city: str: Optional; The person’s home city
zip_code: str: Optional; Numeric characters. Trailing wildcard allowed
age; int: Optional; One or more integers. Trailing wildcard allowed
dob; str: Optional; Numeric characters in YYYYMMDD format. Trailing wildcard allowed
phone; str: Optional; Integer followed by 0 or more * or integers
email: str: Optional; Alphanumeric character followed by 0 or more * or legal characters (alphanumeric, @, -, .)
unparsed_full_address: str: Optional; One or more alphanumeric characters. No wildcards.

Returns

Parsons Table: See Parsons Table for output options.