Welcome, guest Sign In

Chapter 2. Interacting with the Address Book

Developers can create applications that add, edit and retrieve Address Book content by sending Requests to a specified URL. Address Book data is sent and received in the form of XML or JSON data structures. For more information, see Data Representation.

Searching the Address Book

The method searchContacts retrieves a subset of the user's address book given a set of search criteria specified by URL parameters. The general format of the response produced by the searchContacts method is:

For example, the following request looks for the string "eva" inside all fields and all category names in a user's address book.

A typical response returned by the preceding searchContacts request in JSON format is:

The same result returned in XML format:

Note

The searchContacts method is read-only; read access must be granted by the user.

Parameters

The parameters of the searchContacts method fall into four categories:

  • Contact Criteria

    Finds contacts in the address book.

  • Display Criteria

    Selects which fields will be returned by the search.

  • Paging

    Requests a smaller set of contacts from the returned result set.

  • Bucketing

    Requests a smaller set of contacts from the returned result set, bucketing sorts the results according to specified fields, and divides the results into buckets.

Multiple criteria are separated with an ampersand, '&'. For example, the following request will return the names, phone numbers and email addresses of contacts whose first name starts with "K".

Contact Criteria

The searchContacts method queries the address book to find contacts that match a set of contact criteria on entries in the address book. Contact criteria are specified by parameters in the following format:

fields.condition=values

Multiple contact criteria are "AND"ed together using "&". That is, a contact will match only if all criteria in the request matches. For example, to find all contacts in the address book with a phone number starting with "415" and first name starting with a "K", you could construct the following contact criteria:

Multiple fields and values specified in the criteria result in the "OR" of all field/value combinations. The following criteria will find contacts that have a phone number or an email address, or both:

When building the URL, you must adhere to the following guidelines:

  • URL-encode each acceptable value. For example,

    "Frédérique" becomes "Fr%C3%A9d%C3%A9rique".

  • Join values using ','. For example,

    "a%2Cb,Fr%C3%A9d%C3%A9rique" .

    Notice that the comma character appears in the URL as ',' when it separates values, but it appears as '%2C' when it is part of a value.

  • Join the left hand side and the right hand side parts with '='. For example

    "name.last,name.first.contains=a%2Cb,Fr%C3%A9d%C3%A9rique"

  • At least one non-empty parameter must be specified or an error will be returned.

The following table describes the input that each parameter in the criteria accepts.

Table 2.1. Contact Criteria

Parameter Meaning
fields A comma-separated list of field, components or pseudo-fields. Criteria resulting from each element in the list are "OR"'ed together. Each element in the list can be one of the following:
  • Any of the known, unstructured field types
  • The first, middle or last name of the name field: name.first, name.middle, or name.last
  • all: pseudo-type; matches all fields, including name of the category that the contract is in.
  • category: pseudo-type; matches the name of the category that the contact is in.
  • all-but-category: pseudo-type; matches all fields, but not the name of the category that the contact is in.
  • cid: pseudo-type; matches the Contact ID. Only is and cs-is are valid conditions for use with this pseudo-type. As Contact IDs are numeric, is and cs-is are completely equivalent in this context.
condition One of the following condition keywords:
  • is: case-insensitive comparison of the full field value with value.
  • startswith: case-insensitive comparison of the beginning of the field value with value.
  • contains: case-insensitive comparison of a substring in the field value with value.
  • cs-is: case-sensitive comparison of the full field value with value.
  • cs-startswith: case-sensitive comparison of the beginning of the field value with value.
  • cs-contains: case-sensitive comparison of a substring in the field value with value.
  • present:
    • If value is 1, match only if such a field is present.
    • If value is 0, match only if no such field is present in the contact.

      Note

      In this case, values is not a comma-separated list, and each element in fields must be an unstructured or a structured type from Field Types.

    • Components and pseudo-types are not accepted.
values A comma-separated list of values to match against address book data. Criteria resulting from each value is "OR"ed together. When present is used as condition, only "0" or "1" are valid values, without commas.

Criteria Types

Criteria are classified into four types: 1, 2, 3 and 4. The table below defines which conditions are of which "type":

Table 2.2. Criteria Types

Type Criteria
1 present=1
2 present=0
3 Contains one of the following condition keywords:
  • is
  • startswith
  • contains
  • cs-is
  • cs-startswith
  • cs-contains
4 cid.is= or cid.cs-is= (Criteria restricting the search to the specified Contact IDs.)


Contact Criteria Limitations

  • You can search for the first, middle and last name components of a structured field, but no other components, such as ZIP code.
  • You cannot search by field flag. For example, when searching for a phone, all kinds of phones will match (work, home, mobile). The application needs to make distinctions between field flags.
  • You can combine contact criteria of the same type as long as they do not have multiple field references. In other words, you cannot combine "AND" and "OR" criteria of the same type. For example,

    is invalid because both criteria are type 1, and the first criteria specifies two fields, while

    is valid.

The following table provides examples of valid and invalid combinations:

Table 2.3. Example Criteria Types

Example Criteria Valid or Invalid Reason

phone,email.present=1 &address.present=1 

 Invalid Invalid because it is an AND of two criteria type "1", the first of which has multiple fields: phone and email.

phone,email.present=1 &address.present=0

 Valid Valid because it is an AND of a criteria type "1" and "2".

phone.startswith=415 &name.first, name.last.startswith=K

 Invalid Invalid because it is an AND of two type "3" criteria, the second one of which has multiple fields.

phone.startswith=415 &name.first.startswith=K

 Valid Valid because it is an AND of two single field type "3" criteria.

phone.startswith=415 &all.startswith=K

 Valid Valid because it is an AND of two single field type "3" criteria.
cid.is=14,18,20 Valid Valid, returns contacts with IDs 14, 18 and 20 if they exist. Non-existent contacts will not cause an error, they will be simply absent from the result.

cid.is=14,18,20 &phone.present=1

 Valid Valid, returns those contacts with Contact ID either 14, 18 or 20, which also have a phone field. If no contacts satisfy both conditions simultaneously, the result set will be empty.

Display Criteria

The searchContacts method accepts parameters that specify which fields are returned and how they will be displayed. Display criteria are not coupled with contact criteria in any way.

Specify display criteria using the following parameters:

Table 2.4. Display Criteria

Parameter Meaning
fields A comma-separated list of field types to return. If the fields parameter is omitted, all fields are returned. The list of fields to return can also contain any combination of the following pseudo-field specifications:
  • all: include all fields. This is the default if the fields parameter is omitted. The pseudo-fields displayaddress and displayname below are not implied by all. If you want all field types to be returned including displayaddress and displayname you can specify: &fields=all,displayaddress,displayname.
  • displayaddress: implies address and adds to the output a formatted (flattened) rendering of each address field as the pseudo-field displayaddress.
  • displayname: implies name and also adds a pseudo-field displayname to the output which contains the "name-line"; for example, a summary line for the contact similar to how the Address Book UI presents a contact on the contact list page, which consists in an international-formatted name if there is a name field, or otherwise the value of some other significant field such as company, yahooid or phone.
sort-fields A comma-separated list of Field Types specifying which fields to use for sorting. The first field in the list is the primary sort criteria; the second and subsequent fields are used to disambiguate.
sort Sort order: asc (default) for ascending; desc for descending.

The following sample request returns contacts whose first name starts with "K". Only contacts containing a phone number or an email address are returned. The names, phone numbers and email address of matching contacts are returned.

Paging

Paging is used to request a smaller set of contacts out of a larger result set. When paging is in effect, Address Book servers perform the search, sort the result according to sort fields (or the default sort criteria), and then extract a range from the sorted list of matches.

Table 2.5. Paging Parameters

Parameter Meaning
page Specifies the page number to return; 0 is the first page in the sort-order.
pagesize Specifies the number of contacts per page.

If N is the total number of matching contacts, S is the page size and P is the requested page-number, the following (possibly empty, inclusive) range of matches will be returned:

P*S -- min(N,(P+1)*S-1)

When paging is in effect, the response entity will contain the attribute total-matches: total number of matching contacts, of which only a page is returned.

The following sample request returns the first page (with five contacts per page) of contacts whose first name starts with "K". Only contacts containing a phone number or an email address are returned. The names, phone numbers and email address of matching contacts are returned. Contacts are returned sorted by first name.

Sample response:

Bucketing

Bucketing is another way to request a subset of contacts out of a larger result set. When bucketing is in effect, Address Book servers perform the search, sort the result according to sort-fields (or the default sort criteria), and split the result into buckets. Contacts in one of these buckets, specified by bucket, are returned in full and called the current bucket. For all other buckets, the first and the last contact in the bucket is returned and called the bucket header (unless the header is disabled with nobucketheader).

Table 2.6. Bucketing Parameters

Parameter Meaning
bucket The 0-based number of the bucket to return. 0 is the first bucket in the sort-order
maxbucketsize The preferred maximum number of contacts per bucket
minbucketcount The preferred minimum number of buckets
nobucketheader If 1, the bucket header will be omitted from the response

When bucketing is in effect, the response has the following structure:

Table 2.7. Bucketing Response Items

Value Meaning
total-matches Total number of matching contacts
buckets The bucket header: summary of buckets other than the current bucket (bucket that is returned in full)
  • id: the (0-based) number of this bucket (the fully expanded bucket will be left out from the header)
  • contact-count: number of contacts that fall into this bucket
  • start: the first contact that falls into this bucket
  • end: the last contact that falls into this bucket
contacts Contacts in the current bucket (bucket that is returned in full)

Table of Contents

Copyright © 2009 Yahoo! Inc. All rights reserved. Copyright | Privacy Policy

Help us continue to improve the Yahoo! Developer Network: Send Your Suggestions