SYNOPSIS

use WWW::Google::Contacts;

my $google = WWW::Google::Contacts->new( username => "your.username", password => "your.password" );

my $contact = $google->new_contact;
$contact->full_name("Emmett Brown");

A lot of fields, such as email, phone number and so on, are accessible as array refs.

foreach my $email (@{ $contact->email }) {
   print "He got email address: " . $email->value . "\n";
}

When you have made changes to your contact, you need to save them back to Google. This is done either by a create call (for new contacts) or an update call (for existing contacts).

$contact->create;

Alternatively, you can use the create_or_update method, which will do the right thing.

$contact->create_or_update;

METHODS

$contact->create

Writes the contact to your Google account.

$contact->retrieve

Fetches contact details from Google account.

$contact->update

Updates existing contact in your Google account.

$contact->delete

Deletes contact from your Google account.

$contact->create_or_update

Creates or updates contact, depending on if it already exists.

ATTRIBUTES

All these attributes are gettable and settable on Contact objects.

given_name

$contact->given_name("Arnold");

additional_name

$contact->additional_name("J");

family_name

$contact->family_name("Rimmer");

name_prefix

$contact->name_prefix("Mrs");

name_suffix

$contact->name_suffix("III");

full_name

If this is set to what seems like "$given_name $family_name", those attributes will be automatically set.

email

$contact->email is, if defined, an array reference with 1 or more Email objects. The Email objects have the following accessors;

type: This is an object in itself, which has 2 accessors; name and uri.
label: If you don't want to use the predefined types (defined by Google) you can set this label instead.
value: The email address.
display_name: An optional display name.
primary: A boolean stating whether this is the primary email address.

Example code (set the first work email as the primary address):

foreach my $email (@{ $contact->email }) {
  if ( $email->type->name eq 'work' ) {
    $email->primary(1);
    last;
  }
}

Explicitly setting all email details:

$contact->email({
  type => "work",
  value => 'shenanigans@example.com',
  display_name => 'Shenanigans',
  primary => 1,
});

Note that this will overwrite any previous email addresses for the contact. To add rather than replace, see add_email below.

If you're just setting the email value, type will default to "work" and leave other fields empty.

$contact->email( 'smeghead@reddwarf.net' );

To specify several email addresses, you could either;

provide them all in an array

$contact->email([
   { type => "work", value => 'underpaid@bigcompany.com' },
   { type => "home", value => 'angryblogger@someblogsite.com' },
]);

call add_email

$contact->add_email( 'homer@simpson.name' );

phone_number

$contact->phone_number is, if defined, an array reference with 1 or more PhoneNumber objects. The PhoneNumber objects have the following accessors;

type: This is an object in itself, which has 2 accessors; name and uri.
label: If you don't want to use the predefined types (defined by Google) you can set this label instead.
value: The phone number

Explicitly setting all phone details:

$contact->phone_number({
  type => "mobile",
  value => "+449812323",
});

Just setting the value will set type to default value "mobile".

$contact->phone_number( "+1666666" );

To specify several phone numbers, you could either;

provide them all in an array

$contact->phone_number([
   { type => "mobile", value => "12345" },
   { type => "home", value => "666" },
]);

call add_phone_number

$contact->add_phone_number({
   type => "home",
   value => "02078712345"
});

im (Instant Messaging)

$contact->im is, if defined, an array reference with 1 or more IM objects. The IM objects have the following accessors;

type

This is an object in itself, which has 2 accessors; name and uri.

label

If you don't want to use the predefined types (defined by Google) you can set this label instead.

protocol

This is an object in itself, which has 2 accessors; name and uri.

Which protocol is used for this IM address. Possible name values include AIM, MSN, YAHOO. SKYPE, QQ, GOOGLE_TALK, ICQ, JABBER.

value

Email address for the IM account.

You can specify all IM details:

$contact->im({
  type => "home",
  protocol => "MSN",
  value => 'some.email@example.com',
});

Or you can just choose to give the IM address:

$contact->im( 'some.email@example.com' );

organization

$contact->organization is, if defined, an array reference with 1 or more Organization objects. The Organization objects have the following accessors;

type: This is an object in itself, which has 2 accessors; name and uri.
label: If you don't want to use the predefined types (defined by Google) you can set this label instead.
department: Specifies a department within the organization.
job_description: Description of a job within the organization.
name: The name of the organization.
symbol: Symbol of the organization.
title: The title of a person within the organization.
primary: Boolean. When multiple organizations extensions appear in a contact kind, indicates which is primary. At most one organization may be primary.
where: A place associated with the organization, e.g. office location.

postal_address

$contact->postal_address is, if defined, an array reference with 1 or more PostalAddress objects. The PostalAddress objects have the following accessors;

type

This is an object in itself, which has 2 accessors; name and uri.

label

If you don't want to use the predefined types (defined by Google) you can set this label instead.

mail_class

This is an object in itself, which has 2 accessors; name and uri.

Classes of mail accepted at the address. Possible name values are both, letters, parcels and neither. Unless specified both is assumed.

usage

This is an object in itself, which has 2 accessors; name and uri

The context in which this addess can be used. Possible values are general and local. Local addresses may differ in layout from general addresses, and frequently use local script (as opposed to Latin script) as well, though local script is allowed in general addresses. Unless specified general usage is assumed.

primary

Boolean. Specifies the address as primary.

agent

The agent who actually receives the mail. Used in work addresses. Also for 'in care of' or 'c/o'.

house_name

Used in places where houses or buildings have names (and not necessarily numbers), eg. "The Pillars".

street

Can be street, avenue, road, etc. This element also includes the house number and room/apartment/flat/floor number.

pobox

Covers actual P.O. boxes, drawers, locked bags, etc. This is usually but not always mutually exclusive with street.

neighborhood

This is used to disambiguate a street address when a city contains more than one street with the same name, or to specify a small place whose mail is routed through a larger postal town. In China it could be a county or a minor city.

city

Can be city, village, town, borough, etc. This is the postal town and not necessarily the place of residence or place of business.

subregion

Handles administrative districts such as U.S. or U.K. counties that are not used for mail addressing purposes. Subregion is not intended for delivery addresses.

region

A state, province, county (in Ireland), Land (in Germany), departement (in France), etc.

postcode

Postal code. Usually country-wide, but sometimes specific to the city (e.g. "2" in "Dublin 2, Ireland" addresses).

country

An object with two accessors; name and code.

formatted

The full, unstructured postal address.

billing_information

Specifies billing information of the entity represented by the contact.

notes

Arbitrary notes about your friend.

$contact->notes( "He's a lumberjack, but he's ok" );

birthday

If defined, returns an object with one accessor;

when: Birthday date, given in format YYYY-MM-DD (with the year), or --MM-DD (without the year).

...tba

Sorry, haven't documented all attributes yet :(

INTERACTION WITH GROUPS

Contacts can belong to 0 or more groups. This section describes how to get and set group memberships.

$contact->groups

Returns an array reference of all groups, as WWW::Google::Contacts::Group objects.

$contact->add_group_membership( group )

The group argument can either be:

An WWW::Google::Contacts::Group object
The ID of a group, as a URL
The name of a group

Do note that the group has to exist on the Google servers before you can add this membership.

AUTHOR

Magnus Erixzon <magnus@erixzon.com>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as perl itself.

To install WWW::Google::Contacts, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WWW::Google::Contacts

CPAN shell

perl -MCPAN -e shell
install WWW::Google::Contacts

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

SYNOPSIS

METHODS

$contact->create

$contact->retrieve

$contact->update

$contact->delete

$contact->create_or_update

ATTRIBUTES

given_name

additional_name

family_name

name_prefix

name_suffix

full_name

email

phone_number

im (Instant Messaging)

organization

postal_address

billing_information

notes

birthday

...tba

INTERACTION WITH GROUPS

$contact->groups

$contact->add_group_membership( group )

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions