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.targetsmart.targetsmart_api.TargetSmartAPI(api_key=None)[source]
data_enhance(search_id: Literal['voterbase', 'exacttrack', 'phone', 'email', 'smartvan', 'votebuilder', 'voter', 'household'], search_id_type='voterbase', state=None)

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

Parameters:

  • 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: Literal['zip', 'address', 'point'] = '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
Parameters:

  • 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

Parameters:

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

Parameters:

  • 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, disable_automatic_matchback_id_creation=False, max_matches=1, include_email=False, include_landline=False, include_wireless=False, include_voip=False, tmp_location=None, join_with_input_table=True, 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.

Parameters:

  • input_table – Parsons or Petl table A Parsons table with header field names supported by SmartMatch. Required.

  • disable_automatic_matchback_id_creation – bool Set to True to disable auto creation of matchback_id. Default of False.

  • 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.

  • join_with_input_table – bool Set to True to include input table in ouput parsons table. Default is True.

  • 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.

Parameters:

  • 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

  • int (age;) – Optional; One or more integers. Trailing wildcard allowed

  • str (phone;) – Optional; Numeric characters in YYYYMMDD format. Trailing wildcard allowed

  • 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.