getTeamraisersByDistance

Returns a list of TeamRaiser events that match the search criteria provided. Search criteria includes the starting zip/postal code, the distance to search from that starting zip/postal code, and the units of distance to use (miles or kilometers).

Client Servlet Server Servlet HTTP Methods Supported Requires Authentication
CRTeamraiserAPI None. GET, POST No.

Client API Syntax

https://secure2.convio.net/organization/site/CRTeamraiserAPI?method=getTeamraisersByDistance &api_key=value &v=value [ &center_id=value ] [ &error_redirect=value ] [ &redirect=value ] [ &response_format=xml | json ] [ &sign_redirects=value ] [ &source=value ] [ &sub_source=value ] [ &success_redirect=value ] [ &suppress_response_codes=value ] &starting_postal=value [ &distance_units=km | mi ] [ &event_type=value ] [ &full_search=value ] [ &list_ascending=value ] [ &list_category_id=value ] [ &list_filter_column=value ] [ &list_filter_text=value ] [ &list_page_offset=value ] [ &list_page_size=value ] [ &list_record_offset=value ] [ &list_sort_column=value ] [ &public_event_type=value ] [ &search_distance=value ]

Usage Notes

This client-only method returns a list of active TeamRaiser Events located based off distance from a starting zip or postal code. Use this to provide your users with the ability to locate the closest event to them.

Note: An Active event is an event that is Accepting Gifts, Accepting Registrations, or Accepting Gifts and Registrations.
Note: Currently, the distance search only supports Zip Codes within the United States.

This method shares several features with getTeamraisersByInfo, including the ability to limit the search to Teamraiser Events within a given Security Category or Primary Event Type. To limit the search to a given Security Category, use the list_category_id to provide the Category ID to limit the search to. To limit the search to a given Primary Event Type, use the event_type parameter to specify the name of the Primary Event Type. If you provide the name of a Primary Event Type that does not exist, an error message will be thrown.

You can use these parameters to limit the search in ways that your users may not be familiar with. One example would be that if your organization has several chapters, divisions or affiliates and each wants their own search page to locate only their events. You can include the security category ID for that affiliate as a hidden form field to ensure that the search returns only events within that affiliate's category. If you have separate programs within each affiliate and want each program to have it's own search page, include the primary event type that identifies that program and the security category id for that affiliate.

Additionally, the list that is returned supports several parameters allowing finer control of the results, including filtering on any of the returned elements, pagination, and sorting.

Paginating the List takes two parameters: list_page_size, which specifies the number of results to be retrieved for that page. You must also provide one of the following two parameters:
  • list_page_offset: specifies which page of the results to retrieve. The first page of results has a list_page_offset of 0, page 2 has a list_page_offset of 1, and so on.
  • list_record_offset: specifies which record the page should start with. This also uses numbering from 0, so the first record has a list_record_offset of 0, the 2nd record has a list_record_offset of 1, and so on.
Filtering the List takes two parameters:
  • list_filter_column: name of the element to be filtered on.
  • list_filter_text: text that the element specified by list_filter_column must contain.
Note: list_filter_text performs an exact match, and is case sensitive.
Sorting the List takes two parameters:
  • list_sort_column: name of the element to be sorted by.
  • list_ascending: Boolean value indicating whether the sort should be in ascending order
Note: You can paginate, filter, and sort the list all in one call.
Things to know when using this method:
  • US Zip codes should be the 5-digit zip code.
  • Searches may be performed in either Miles or Kilometers, but the maximum search distance is 200 (either 200 miles or 200 kilometers)
  • Event Type limitations only support Primary Event Types.

Client API Parameters

Common Client Parameters

See topic Common Parameters.

starting_postal

Required. The starting zip code to use for a distance search. For US Zip Codes, use the 5-digit zip code. Currently only supports US Zip Codes.

Type xsd:string.

distance_units

Optional. The Unit of distance measurements to use for a distance search. Can be either 'mi' for miles or 'km' for kilometers. Default value is 'mi'.

Type xsd:string.

Default is mi.

Options are:
  • km
  • mi
event_type

Optional. The name of the Primary Event Type to limit search results to. Omit this parameter to search on all Primary Event Types. Defaults to null.

Type xsd:string.

full_search

Optional. If TRUE, returns all events regardless of event status, otherwise returns only published events. Possible status values include: Unpublished = 0, Accepting Registrations Only = 1, AcceptingRegistrations and Gifts = 2, Accepting Gifts Only= 3, Closed = 4, Archived = 8, Deleted = 9.

Type xsd:boolean.

list_ascending

Optional. Whether the list should be sorted in ascending order.

Type xsd:boolean.

Default is true.

list_category_id

Optional. Security Category filter.

Type xsd:integer.

list_filter_column

Optional. The database column that will be used to match the filter text (used with "list_filter_text").

Type xsd:string.

list_filter_text

Optional. The text that will be used to filter results.

Type xsd:string.

list_page_offset

Optional. The requested page number (used with "list_page_size"). The first page (default) is zero. Only one of "list_record_offset" or "list_page_offset" should be used in a request.

Type xsd:integer.

list_page_size

Optional. The number of results in each page (used with "list_record_offset" or "list_page_offset").

Type xsd:integer.

Default is 25.

list_record_offset

Optional. The requested initial record number (used with "list_page_size"). The first record (default) is zero. Only one of "list_record_offset" or "list_page_offset" should be used in a request.

Type xsd:integer.

list_sort_column

Optional. The column to sort with (used with "list_ascending").

Type xsd:string.

public_event_type

Optional. The case-sensitive name of the Public Event Type to limit search results to. Omit this parameter to search on events with any Public Event Type. Defaults to null.

Type xsd:string.

search_distance

Optional. The radius to search within from the starting zip / postal code. Must be a number from 0-200, defaults to 0.

Type xsd:integer.

Default is 0.

Response

See topic HTTP Status Codes.

XML response 
<?xml version="1.0" encoding="UTF-8"?>
<getTeamraisersResponse xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd" xmlns="http://convio.com/crm/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <totalNumberResults>3</totalNumberResults>
  <teamraiser>
    <id>12000</id>
    <name>Sample Event Title 0</name>
    <description>Sample Event Description 0</description>
    <event_date>2016-02-01T09:43:39.936-06:00</event_date>
    <accepting_registrations>true</accepting_registrations>
    <accepting_donations>true</accepting_donations>
    <location_name>Sample Location 0</location_name>
    <street_address>1234 Fake St.</street_address>
    <city>Austin</city>
    <state>TX</state>
    <zip>78758</zip>
    <county>Travis</county>
    <country>United States</country>
    <region>Hill Country</region>
    <area>North Austin</area>
    <mailingAddrAttn>J. Doe</mailingAddrAttn>
    <mail_street1>1234 Fake Ave.</mail_street1>
    <mail_street2>Suite 1000</mail_street2>
    <mail_city>Austin</mail_city>
    <mail_state>TX</mail_state>
    <mail_zip>78758</mail_zip>
    <status>1</status>
    <greeting_url>http://example.com/greetingUrl</greeting_url>
    <find_url>http://example.com/findTeamOrParticipantUrl</find_url>
    <donate_event_url>http://example.com/donateUrl</donate_event_url>
    <reg_indiv_url>http://example.com/registerIndividualUrl</reg_indiv_url>
    <reg_new_team_url>http://example.com/formANewTeamUrl</reg_new_team_url>
    <reg_join_team_url>http://example.com/joinTeamUrl</reg_join_team_url>
    <public_event_type_name>Central Texas</public_event_type_name>
    <ecommerce_event_url>http://example.com/eCommerceEventUrl</ecommerce_event_url>
    <customized_url>http://example.com/customizedUrl</customized_url>
    <distance>10.0</distance>
  </teamraiser>
  <teamraiser>
    <id>12001</id>
    <name>Sample Event Title 1</name>
    <description>Sample Event Description 1</description>
    <event_date>2016-02-01T09:43:39.950-06:00</event_date>
    <accepting_registrations>true</accepting_registrations>
    <accepting_donations>true</accepting_donations>
    <location_name>Sample Location 1</location_name>
    <street_address>1234 Fake St.</street_address>
    <city>Austin</city>
    <state>TX</state>
    <zip>78758</zip>
    <county>Travis</county>
    <country>United States</country>
    <region>Hill Country</region>
    <area>North Austin</area>
    <mailingAddrAttn>J. Doe</mailingAddrAttn>
    <mail_street1>1234 Fake Ave.</mail_street1>
    <mail_street2>Suite 1000</mail_street2>
    <mail_city>Austin</mail_city>
    <mail_state>TX</mail_state>
    <mail_zip>78758</mail_zip>
    <status>1</status>
    <greeting_url>http://example.com/greetingUrl</greeting_url>
    <find_url>http://example.com/findTeamOrParticipantUrl</find_url>
    <donate_event_url>http://example.com/donateUrl</donate_event_url>
    <reg_indiv_url>http://example.com/registerIndividualUrl</reg_indiv_url>
    <reg_new_team_url>http://example.com/formANewTeamUrl</reg_new_team_url>
    <reg_join_team_url>http://example.com/joinTeamUrl</reg_join_team_url>
    <public_event_type_name>Central Texas</public_event_type_name>
    <ecommerce_event_url>http://example.com/eCommerceEventUrl</ecommerce_event_url>
    <customized_url>http://example.com/customizedUrl</customized_url>
    <distance>11.0</distance>
  </teamraiser>
  <teamraiser>
    <id>12002</id>
    <name>Sample Event Title 2</name>
    <description>Sample Event Description 2</description>
    <event_date>2016-02-01T09:43:39.951-06:00</event_date>
    <accepting_registrations>true</accepting_registrations>
    <accepting_donations>true</accepting_donations>
    <location_name>Sample Location 2</location_name>
    <street_address>1234 Fake St.</street_address>
    <city>Austin</city>
    <state>TX</state>
    <zip>78758</zip>
    <county>Travis</county>
    <country>United States</country>
    <region>Hill Country</region>
    <area>North Austin</area>
    <mailingAddrAttn>J. Doe</mailingAddrAttn>
    <mail_street1>1234 Fake Ave.</mail_street1>
    <mail_street2>Suite 1000</mail_street2>
    <mail_city>Austin</mail_city>
    <mail_state>TX</mail_state>
    <mail_zip>78758</mail_zip>
    <status>1</status>
    <greeting_url>http://example.com/greetingUrl</greeting_url>
    <find_url>http://example.com/findTeamOrParticipantUrl</find_url>
    <donate_event_url>http://example.com/donateUrl</donate_event_url>
    <reg_indiv_url>http://example.com/registerIndividualUrl</reg_indiv_url>
    <reg_new_team_url>http://example.com/formANewTeamUrl</reg_new_team_url>
    <reg_join_team_url>http://example.com/joinTeamUrl</reg_join_team_url>
    <public_event_type_name>Central Texas</public_event_type_name>
    <ecommerce_event_url>http://example.com/eCommerceEventUrl</ecommerce_event_url>
    <customized_url>http://example.com/customizedUrl</customized_url>
    <distance>12.0</distance>
  </teamraiser>
</getTeamraisersResponse>
JSON response 
{"getTeamraisersResponse":{"teamraiser":[{"region":"Hill Country","state":"TX","city":"Austin","id":"12000","distance":"10.0","reg_new_team_url":"http://example.com/formANewTeamUrl","mail_state":"TX","area":"North Austin","description":"Sample Event Description 0","name":"Sample Event Title 0","mail_city":"Austin","reg_indiv_url":"http://example.com/registerIndividualUrl","ecommerce_event_url":"http://example.com/eCommerceEventUrl","public_event_type_name":"Central Texas","zip":"78758","reg_join_team_url":"http://example.com/joinTeamUrl","location_name":"Sample Location 0","status":"1","customized_url":"http://example.com/customizedUrl","find_url":"http://example.com/findTeamOrParticipantUrl","country":"United States","accepting_donations":"true","donate_event_url":"http://example.com/donateUrl","greeting_url":"http://example.com/greetingUrl","county":"Travis","event_date":"2016-02-01T09:43:39.961-06:00","mail_zip":"78758","mailingAddrAttn":"J. Doe","street_address":"1234 Fake St.","accepting_registrations":"true","mail_street1":"1234 Fake Ave.","mail_street2":"Suite 1000"},{"region":"Hill Country","state":"TX","city":"Austin","id":"12001","distance":"11.0","reg_new_team_url":"http://example.com/formANewTeamUrl","mail_state":"TX","area":"North Austin","description":"Sample Event Description 1","name":"Sample Event Title 1","mail_city":"Austin","reg_indiv_url":"http://example.com/registerIndividualUrl","ecommerce_event_url":"http://example.com/eCommerceEventUrl","public_event_type_name":"Central Texas","zip":"78758","reg_join_team_url":"http://example.com/joinTeamUrl","location_name":"Sample Location 1","status":"1","customized_url":"http://example.com/customizedUrl","find_url":"http://example.com/findTeamOrParticipantUrl","country":"United States","accepting_donations":"true","donate_event_url":"http://example.com/donateUrl","greeting_url":"http://example.com/greetingUrl","county":"Travis","event_date":"2016-02-01T09:43:39.963-06:00","mail_zip":"78758","mailingAddrAttn":"J. Doe","street_address":"1234 Fake St.","accepting_registrations":"true","mail_street1":"1234 Fake Ave.","mail_street2":"Suite 1000"},{"region":"Hill Country","state":"TX","city":"Austin","id":"12002","distance":"12.0","reg_new_team_url":"http://example.com/formANewTeamUrl","mail_state":"TX","area":"North Austin","description":"Sample Event Description 2","name":"Sample Event Title 2","mail_city":"Austin","reg_indiv_url":"http://example.com/registerIndividualUrl","ecommerce_event_url":"http://example.com/eCommerceEventUrl","public_event_type_name":"Central Texas","zip":"78758","reg_join_team_url":"http://example.com/joinTeamUrl","location_name":"Sample Location 2","status":"1","customized_url":"http://example.com/customizedUrl","find_url":"http://example.com/findTeamOrParticipantUrl","country":"United States","accepting_donations":"true","donate_event_url":"http://example.com/donateUrl","greeting_url":"http://example.com/greetingUrl","county":"Travis","event_date":"2016-02-01T09:43:39.964-06:00","mail_zip":"78758","mailingAddrAttn":"J. Doe","street_address":"1234 Fake St.","accepting_registrations":"true","mail_street1":"1234 Fake Ave.","mail_street2":"Suite 1000"}],"totalNumberResults":"3"}}

Examples

To perform a Distance search looking for any events within 25 miles of the Zip Code 78758: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=MyAPIKey&v=1.0&method=getTeamraisersByDistance&starting_postal=78758&search_distance=25&distance_units=mi

Same as above, but limiting the search to events with a Primary Event Type of "Walks", and only retrieving the first page of results, displaying 10 results per page: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=MyAPIKey&v=1.0&method=getTeamraisersByDistance&starting_postal=78758&search_distance=25&distance_units=mi&event_type=Walks&list_page_size=10&list_page_offset=0

Same as above, but sorting the results by distance:

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=MyAPIKey&v=1.0&method=getTeamraisersByDistance&starting_postal=78758&search_distance=25&distance_units=mi&event_type=Walks&list_page_size=10&list_page_offset=0&list_ascending=true&list_sort_column=distance

Retrieving Page 2 of the above query: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=MyAPIKey&v=1.0&method=getTeamraisersByDistance&starting_postal=78758&search_distance=25&distance_units=mi&event_type=Walks&list_page_size=10&list_page_offset=1&list_ascending=true&list_sort_column=distance

A Distance search looking for any events within 200 kilometers of the Zip Code 20037: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=MyAPIKey&v=1.0&method=getTeamraisersByDistance&starting_postal=20037&search_distance=200&distance_units=km

Same as above, but selecting 20 results per page starting with result #5, sorting by name in descending order, filtered to events with an area of Capitol Hill: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=MyAPIKey&v=1.0&method=getTeamraisersByDistance&starting_postal=20037&search_distance=200&distance_units=km&list_page_size=20&list_record_offset=5&list_filter_column=area&list_filter_text=Capitol%20Hill&list_sort_column=name&list_ascending=false
Parent topic: TeamRaiser API
Previous topic: getTeamraiserSuggestion
Next topic: getTeamraisersByInfo

Leave a Comment

Nickname
Comment
Enter this word:
Change