Warning

The XML-RPC API is deprecated, and will be removed on July 1, 2023.

Please use the REST API instead.

Contact support if you need help with migration, or need the feature enabled on a transitional basis.

Targets

Targets are the elected officials, private citizens, companies or organizations to whom you direct your petitions, calls and letters.

Note

Targets are divided into several types - house, senate, state_house, state_senate, and other. You can only update ( save or create ) Targets of type other via the API.

Targets are organized into groups, CongressTargetGroups or SpecialTargetGroups. TargetGroups define the subset of officials or other targets your action is trying to influence.

CongressTargetGroups have rules about finding elected officials, e.g. all Democrats elected to Congress from PA. CongressTargetGroups can include Targets of type 'house', 'senate', 'state_house', and 'state_senate'. You might create a CongressTargetGroup for all the key votes on an upcoming piece of legislation. Or for all the Democrats in the U.S. House in a specific list of states.

SpecialTargetGroups can be anyone.

You can search for CongressTargets by zip, district and user. ActionKit gives you access to legislators in the U.S. House and U.S. Senate, as well as state House and state Senate.

CallPages, LetterPages and PetitionPages can have one or more TargetGroups associated with them. You can add and remove TargetGroups from Pages using the API.

Target

The base class for all Target objects.

Fields

Target objects all have the following fields, which map to columns in the core_target table:

  • type - house, senate, state_house, state_senate, other
  • country
  • state
  • seat - For senators at the federal and state level
  • us_district - For representatives at the federal and state level
  • district_name - Friendly name of district (US and International)
  • title
  • long_title
  • first
  • last
  • phone
  • fax
  • email
  • gender - In the admin this field is labeled "Pronouns" but identified in the database as "gender". Options are Null for They/Them/Theirs; M for He/Him/His; or F for She/Her/Hers
  • party - D, R and I are standard.

Methods

Targets support the common API methods with a few changes, notably that save, create and save_or_create only allow changes to Targets of type other. See the Target for the details.

Targets also support a number of methods to help using them in text. See TargetList for more details.

get

>>> actionkit.Target.get(dict(us_district='PA_07', type='house'))
{'country': 'United States',
 'email': 'https://meehan.house.gov/contact-me/email-me',
 'fax': '(202) 226-0280',
 'first': 'Patrick',
 'gender': 'M',
 'id': 7808,
 'last': 'Meehan',
 'long_title': 'Representative',
 'party': 'R',
 'phone': '(202) 225-2011',
 'seat': '',
 'state': 'PA',
 'title': 'Rep.',
 'type': 'house',
 'us_district': 'PA_07'}

create

You can only create or update (save) Targets of type 'other'. For all other changes, please contact ActionKit.

Note

Submitting your fixes to the legislative data to ActionKit allows us to share the fixes with all our clients and to make sure our vendors get the updates as well.

>>> actionkit.Target.create(dict(first='Mr.', last='Smith', type='other'))
{'country': '',
 'email': '',
 'fax': '',
 'first': 'Mr.',
 'gender': '',
 'id': 8141,
 'last': 'Smith',
 'long_title': '',
 'party': '',
 'phone': '',
 'seat': '',
 'state': '',
 'title': '',
 'type': 'other',
 'us_district': ''}

save

Save requires the id of the target you want to update. You an only update Targets of type 'other'. For all other changes please submit a request to ActionKit.

>>> actionkit.Target.save(dict(id=8141, phone='212 555 1212'))
{'country': '',
 'email': '',
 'fax': '',
 'first': 'Mr.',
 'gender': '',
 'id': 8141,
 'last': 'Smith',
 'long_title': '',
 'party': '',
 'phone': '212 555 1212',
 'seat': '',
 'state': '',
 'title': '',
 'type': 'other',
 'us_district': ''}

zip_to_district

Find a U.S. Congressional District using a zip code.

Note

Zip codes may be in several districts! ActionKit will return the largest district in a zip code. For more precise results, provide a plus-4.

>>> actionkit.Target.zip_to_district(dict(zip='19130'))
'PA_01'

>>> actionkit.Target.zip_to_district(dict(zip='19130',plus4='3036'))
'PA_02'

zip_to_city_and_state

Find the city and state for a zip code:

>>> actionkit.Target.zip_to_city_and_state(dict(zip='19130'))
{'city': 'Philadelphia', 'state': 'PA'}

zip_details

Find some more information about a zip:

>>> actionkit.Target.zip_details(dict(zip='19130'))
{'city': 'Philadelphia',
 'county': 'Philadelphia',
 'latitude': 39.968499999999999,
 'longitude': -75.173100000000005,
 'state': 'PA'}

CongressTargetGroup

CongressTargetGroups allow you to define a set of Targets based on the Targets elected office, state, or party. You can also explicitly include or exclude Targets from a CongressTargetGroup.

Fields

  • type - house, state_house, senate, state_senate, other
  • name - a unique name
  • include_republicans - True or False
  • include_democrats - True or False
  • include_independents - True or False
  • states - a list of state codes, separated by commas or semi-colons
  • targets - a list of Targets to include
  • excludes - a list of Targets to exclude

Built-in CongressTargetGroups

ActionKit has three built in CongressTargetGroups, U.S. House, U.S. President, U.S. Senate. State House and Senate are also available although you have to 'activate' them by creating a CongressTargetGroup if you want to see them in admin.

Methods

all_targets

Use all_targets to load a TargetList of the full set of Targets from a TargetGroup. This isn't very useful for the built-in TargetGroups, but it works:

us_house = actionkit.CongressTargetGroup.all_targets(dict(
    name='U.S. House'
))

It's more useful when you've defined a TargetGroup and are not limiting signatures to constituents. See create below for an example.

targets_for_user

In some cases you want to find the Rep. for a specific User.

>>> user = actionkit.User.get(dict(email='actionkit@example.com'))
>>> targets = actionkit.CongressTargetGroup.targets_for_user(dict(
...                       name='U.S. House', user=user['id']
...                    ))
>>> targets['title_last']
'Rep. Nadler'

The same code may return two senators, but title_last will still be defined because it returns a TargetList:

>>> user = actionkit.User.get(dict(email='actionkit@example.com'))
>>> targets = actionkit.CongressTargetGroup.targets_for_user(dict(
...       name='U.S. Senate', user=user['id']
... )
>>> targets['title_last']
'Sens. Schumer and Gillibrand'

create

TargetGroups become much more interesting when you define your own. Let's say you're running a campaign to support Democratic State Senators in Wisconsin.

tg = actionkit.CongressTargetGroup.create({'include_democrats':True,
                                           'include_republicans':False,
                                           'include_independents':False,
                                           'states':'WI',
                                           'type':'state_senate',
                                           'name':"Wisconsin 14"})

Now you can easily get a TargetList of these Senators using the name "Wisconsin 14":

thefourteen = actionkit.CongressTargetGroup.all_targets(dict(
                       name='Wisconsin 14'
                   ))
print thefourteen['count']
# 14

CongressTargetGroups that you create also support the method targets_for_user.

targets

You can include or exclude specific Targets from your CongressTargetGroups to create more complicated (or targeted!) groups.

Targets expects a repetively named argument 'targets', which should be a list of ids, and a name or id argument of the CongressTargetGroup.

>>> tg = actionkit.CongressTargetGroup.create(dict(name='My Target Group'))
>>> target = actionkit.Target.get(dict(us_district='PA_07', type='house'))
>>> actionkit.CongressTargetGroup.targets(dict(
...         name='My Target Group',
...         targets=[target['id']]
... ))

excludes

Exclude Targets when you are targeting a large group of legislators, but want to exclude a few. For example, if you are trying to get a group of legislators to sign a letter, you could exclude those who have already signed.

Exclude expects an argument named targets, a list of ids, and a name or id of the CongressTargetGroup.

>>> pa_reps = actionkit.CongressTargetGroup.create(dict(
...                 name="PA State House Ds Who Hate Clean Water",
...                 type='state_house',
...                 include_democrats=True,
...                 include_republicans=False,
...                 include_independents=False,
...                 states='PA'
...           ))
>>> friendlies = actionkit.Target.search(dict(
...                type='state_house',
...                party='D',
...                state='PA'
...                last='Niceguy'
...              ))
>>> actionkit.CongressTargetGroup.excludes(
...     name="PA State House Ds Who Hate Clean Water",
...     targets=[ t['id'] for t in friendlies ]
... )

You can set includes and excludes on any CongressTargetGroup that's not read-only. If you include and exclude the same Target, the Target will be excluded.

You can clear excludes by calling the method with an empty list.

SpecialTargetGroups

SpecialTargetGroups are based on arbitrary lists of Targets. They do not support filtering Targets by party, state or type.

You assign SpecialTargets to a SpecialTargetGroup by setting the 'body' parameter in the create for SpecialTargets to the id of the SpecialTargetGroup. See the example in create below.

Methods

create

Create a new SpecialTargetGroup, 'name' is the only parameter required or allowed.

myspecialtargetgroup = actionkit.SpecialTargetGroup.create(dict(
       name='My Custom Targets',
))

targets

Add targets to a SpecialTargetGroup. If called without the targets parameter, it will return a list of the targets, but see all_targets if you want a TargetList. If called with the targets parameter, it will add the SpecialTargets to the SpecialTargetGroup.

targets = actionkit.SpecialTargetGroup.targets(dict(
            name='My Custom Targets',
            targets=[{ 'title': 'Rep',
                'first': 'Dymondia',
                'last': 'Margaretae',
                'phone': '2125551212',
                'fax':   '2125551212',
                'email': 'dymondia@example.com',
                'gender': 'F' },
            { 'title': 'Rep',
                'first': 'Dasylirion',
                'last': 'Wheeleri',
                'phone': '2125551212',
                'fax':   '2125551212',
                'email': 'dasylirion@example.com',
                'gender': 'M', }
            ]))

all_targets

Return the full list of SpecialTargets as a TargetList.

targets = actionkit.SpecialTargetGroup.all_targets(dict(
             name='My Custom Targets', ))

print targets['title_last'] # Reps Margaretae and Wheeleri

clear_targets

Delete the SpecialTargets in the SpecialTargetGroup from the database.

actionkit.SpecialTargetGroup.clear_targets(dict(
    name='My Custom Targets', ))

TargetList

TargetLists provide additional fields to make it easier to merge references to Targets into text. The field names don't adjust, but the values are pluralized, conjugated or inflected for the number and gender of the Targets. For example, the value associated with 'them' maybe set to he, she or them.

Note

TargetLists are currently only available in English. That's lame and we hope to change it soon!

Fields:

* are
* arent
* checkboxes_html
* count
* do
* dont
* es
* es_verb
* first
* full_name
* have
* havent
* last
* listing_html
* options
* plural
* s
* s_verb
* targets
* their
* theirs
* them
* they
* title_full
* title_last
* were
* werent

TargetLists are returned by the all_targets and targets_for_user methods. You can also create a TargetList from a list of Target ids.

Methods

create

senate = actionkit.Target.search(dict(
          type='senate', state='PA'))
senators = actionkit.TargetList.create(dict(
  targets=[ t['id'] for t in senate]))

house = actionkit.Target.search(dict(
          type='house', state='PA', us_district='PA_07'))
representatives = actionkit.TargetList.create(dict(
  targets=[t['id'] for t in representatives]))

print "Will you call %s to ask %s to sing at the party this weekend?" % \
      (senators['title_last'], senators['them'])
# Will you call Sens. Casey and Toomey to ask them to sing at the party this weekend?

print "Will you call %s to ask %s to sing at the party this weekend?" % \
      (representatives['title_last'], representatives['them'])
# Will you call Rep. Meehan to ask him to sing at the party this weekend?

Pages With Targets

You can use the API to associate TargetGroups with Pages. Call, Petition and Letter pages can be associated with one or more TargetGroups.

Here's an example of creating two TargetGroups, associating them with a Petition and finding Targets for a specific user.

# Create a list of TargetGroups
pa_democrats = [ actionkit.CongressTargetGroup.create(dict(
         name='PA Representatives',
         states='PA',
         type='house'
     )),
     actionkit.CongressTargetGroup.create(dict(
         name='PA Senators',
         states='PA',
         type='senate'
     )), ]


 # Create a PetitionPage and attach the TargetsGroups to it
 petition = actionkit.PetitionPage.create(dict(
     name='savethecacti',
 ))

 target_groups = actionkit.PetitionPage.set_target_groups(dict(
     name='savethecacti',
     target_groups=[ p['id'] for p in pa_democrats ],
 ))

 # Find the full list of Targets for the Petition:
 targets = actionkit.PetitionPage.all_targets_by_type(dict(
     id=petition['id']))

 # Find the specific targets for a user for the Petition
 user = actionkit.User.create(dict(
     name='Juncus Acutus',
     email='juncus@example.com',
     zip='19130',
     plus4='3036',
 ))

 target_list = actionkit.PetitionPage.target_list_for_user(dict(
     id=petition['id'], user=user['id']))

 print "Your targets are %s " % (target_list['title_last'],)
 # Your targets are Rep. Fattah and Sens. Casey and Toomey

Methods

Call Pages, Petition Pages and Letter Pages have the following methods related to Targets.

get_target_groups

Returns the current TargetGroups set for this page.

target_groups = actionkit.PetitionPage.set_target_groups(dict(
            name='savethecacti' ))

set_target_groups

Sets the TargetGroups for this page, clearing any previously associated TargetGroups.

target_groups = actionkit.PetitionPage.set_target_groups(dict(
                name='savethecacti',
                target_groups=[ p['id'] for p in pa_democrats ],
                ))

See retarget_actions below.

all_targets_by_type

Returns a struct of all the possible Targets for this Page categorized by type. Possible types are 'house', 'senate', 'state_house', 'state_senate', and 'other'.

targets = actionkit.PetitionPage.all_targets_by_type(dict(
    id=petition['id']))

target_list_for_user

Returns a TargetList of the Targets for a specific user. For state level targets, the user must have a plus4 on their zip.

Note

Without a plus4, it's not always clear which US congressional district a user lives in. You may want to give your users a way to provide a full address or to pick a representative to deal with ambiguous cases.

target_list = actionkit.PetitionPage.target_list_for_user(dict(
            id=petition['id'], user=user['id']))

retarget_actions

Updates the actions taken to match the current targets.

You can call this method after calling set_target_groups, or you can let ActionKit retarget automatically when you save the page or deliver the signatures.

Returns a count of actions to be retargeted. The actual retargeting will run after this call returns.

estimate = actionkit.LetterPage.retarget_actions(dict(name='mypage'))

See also api.actionkit.LetterPage.retarget_actions()

actions_with_stale_targets

Returns an approximate number of actions to be retargeted.

Note that we only calculate an estimate based time of the last change to the targeting. Even after a call to retarget_actions this count will include actions that cannot be updated to a new target.

estimate = actionkit.LetterPage.actions_with_stale_targets(dict(name='mypage'))
print "Approximately %s actions are stale." % (estimate)

See also api.actionkit.LetterPage.actions_with_stale_targets()