Bucketing

Bucketing is a way to request a subset of contacts from a larger result set and divide that subset into groupings called buckets. Because the returned buckets are indexed, you can request a specific bucket by its index number. The requested bucket contains the specified number of Contact Objects, while the other buckets only contain the first and last Contact Objects of a given range.

For example, suppose John is looking for a contact surnamed Connors on his cell phone and each tab of the address book on his phone represents a bucket. He sees that the contact is not on the selected tab (current bucket) of his address book, which has the contacts surnamed Adams, Ahmed, and Anders. Instead he finds his contact is in the fourth tab, which only has the first and last contacts with the respective surnames Camponi and Daniels. He clicks a button to get the contacts on the fourth tab, which initiates a request to the Contacts API for the fourth bucket. Using pagination, John would have had to scroll through four lists to find his contact, thus, making four requests to the Contacts API. Instead, John gets his contact by making only two requests using bucketing.

Syntax

To get contacts in buckets, use the following syntax:

/v1/user/{guid}/contacts;bucket={var1};maxbucketsize={var2};minbucketcount={var3}?view=bucketinfo

Bucketing should be specified with the following key-value pairs:

  • bucket - the requested bucket that will have the given index. This bucket will have the current field to indicate that it was requested. The HTTP Status Code "404 Not Found" is returned if the bucket is not found.
  • maxbucketsize - the preferred maximum number of Contact Objects returned in each bucket.
  • minbucketcount - the preferred minimum number of buckets returned in each Contact Buckets Object.
  • view=bucketinfo - this is a query parameter that is required for returning the contacts in buckets and metadata about the contents of each bucket. If view=bucketinfo is not present, the returned response will be a Contacts Object without buckets or bucket metadata.

Note

The keys maxbucketsize and minbucketcount are suggested values. The Contacts API will not return an error if the specified values for maxbucketsize and minbucketcount are illegal or exceed the number of a available contacts.

Elements of the Contactbucket Object

Table 3.2. Contactbuckets Object

Element JSON Data Type XML Schema Data Type Description
count number nonNegativeInteger  
current number nonNegativeInteger The number of the current bucket that is requested with the key-value pair bucket={bucket_no}.
totalcontacts number integer The total number of contacts for this user.
buckets Bucket Object Bucket Object A collection of Bucket Objects holding one or more Contact Objects.


Table 3.3. Bucket Object

Element JSON Data Type XML Schema Data Type Description
id number integer The number identifying a Bucket Object, like a array index.
current number nonNegativeInteger The presence of this element with the value "yes" indicates that this bucket was the requested bucket.
start Contact Object Contact Object The first Contact Object in a bucket that was not requested with the key-value pair bucket={bucket_no}.
end Contact Object Contact Object The last Contact Object in a bucket that was not requested with the key-value pair bucket={bucket-no}.
contacts Contacts Object Contacts Object A collection of Contact Objects for the requested bucket.


Bucketing Examples

Use the bucket index, which starts with 0, to request one of the buckets. The requested bucket in the response will have an element called current. The other buckets will have a start element that holds the first Contact Object and an end element that holds the last Contact Object.

Basic Usage:

Divide the contacts for the user with the GUID specified by {guid} into at least five buckets and place at most 10 contacts in the bucket with the index of 1. The header for the bucket is requested with the query parameter view=bucketinfo.

http://social.yahooapis.com/v1/user/{guid}/contacts;bucket=1;maxbucketsize=10;minbucketcount=5?view=bucketinfo

Alphabetical Bucketing by Surname

The URI below does the following in the given order:

  1. Gets all the contacts for the user with the GUID specified by {guid}.
  2. Extracts the contacts whose surnames begin with an 'a' and who have an email.
  3. From each contact, gets only the fields name, nickname, and email.
  4. Sorts the contacts by surname and then by first name.
  5. Places the sorted contacts into at least five buckets. The bucket with the index of 0 will have at most 4 contacts, and the rest of the buckets will have only two contacts: the first and last contacts of the four possible contacts in that range.

http://social.yahooapis.com/v1/user/{guid}/contacts;last.startswith=a;email.present=1;out=name,nickname,email;sort-fields=last,first;sort=asc;bucket=0;maxbucketsize=4;minbucketcount=5?view=bucketinfo

Example Responses

XML Example Response
JSON Example Response

Table of Contents