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.

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.