People Data API Reference Guide

This document provides detailed reference documentation for the OpenSocial People data API.

Important: The OpenSocial People data API hasn't been released yet; this document is a preview of the reference guide that we'll publish when we release the data API. All of the details are subject to change, but this preview should give you a general idea of what the API will be like.

Contents

1. Audience
2. OpenSocial People feed types
3. People versus Friends
4. OpenSocial People query parameters reference
5. OpenSocial People elements reference

Audience

This document is intended for programmers who want to write client applications that can interact with OpenSocial People and Friends.

It's a reference document; it assumes that you understand the general ideas behind AtomPub and the Google data APIs protocol.

OpenSocial People feed types

OpenSocial People provides representations of OpenSocial People data as People and Friend feeds.

The People Feed

The People Feed does not currently support queries for people, though that may be added in future. It is found at:

http://domain/feeds/people/

To find the Person information for a specific individual, use their user id obtained from the OpenSocial APIs, like so:

http://domain/feeds/people/UserID

For example:

http://orkut.com/feeds/people/14358878523263729569

The Friends Feed

The Friends Feed does not currently support queries. To find the Person information for a specific individual, use their user id obtained from the OpenSocial APIs, like so:

http://domain/feeds/people/UserID/friends

For example:

http://orkut.com/feeds/people/14358878523263729569/friends

People versus Friends

Although there is a top-level People endpoint, it does not return anything unless qualified with a person id. Both People and Friends return PersonKind data, and the Friends refer back to the People identifiers.

OpenSocial People query parameters reference

OpenSocial People does not support queries.

OpenSocial People elements reference

In addition to the standard Atom elements, the OpenSocial People data API uses elements from the Google Common elements document and from geoRSS.

Specifically, each entry in the People or Friends feed is a PersonKind, which may contain any or all of the following

Properties

Property	Type	Description
Name	atom:title	The desired display name for the user
Image link	atom:link	With rel="thumbnail", a small image URL to represent the user
Profile URL	atom:link	With rel="alternate", the standard profile URL representing the user
GeoLocation	georss:where	Geographic location of the user. This may be approximate, or rounded off to the nearest city.
email	gd:email	Email address(es) for the user
IM	gd:im	Instant messaging adress(es) for the user
Address	gd:postalAddress	Address(es) for the user.
Phone number	gd:phoneNumber	Telephone number(s) for the user
Key value parameters	gd:extendedProperty	As different social networks and other sources of People data have many different named fields, this provides a way for them to be passed on generally. Agreeing on common naming conventions is to be decided in future.

Example

<entry xmlns='http://www.w3.org/2005/Atom' xmlns:georss='http://www.georss.org/georss' xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://sandbox.orkut.com:80/feeds/people/14358878523263729569</id>
  <updated>2007-10-28T14:01:29.948-07:00</updated>
  <title>Elizabeth Bennet</title>
  <link rel='thumbnail' type='image/*' href='http://img1.orkut.com/images/small/1193601584/115566312.jpg'/>
  <link rel='alternate' type='text/html' href='http://orkut.com/Profile.aspx?uid=17583631990196664929'/>
  <link rel='self' type='application/atom+xml' href='http://sandbox.orkut.com:80/feeds/people/14358878523263729569'/>
  <georss:where>
    <gml:Point xmlns:gml='http://www.opengis.net/gml'>
      <gml:pos>51.668674 -0.066235</gml:pos>
    </gml:Point>
  </georss:where>
  <gd:extendedProperty name='lang' value='en-US'/>
  <gd:postalAddress/>
</entry>

Schema

    # RELAX NG Compact Syntax Grammar
# Description: People API: read-only feed of user profiles

namespace atom = "http://www.w3.org/2005/Atom"
namespace gd = "http://schemas.google.com/g/2005"
namespace georss = "http://www.georss.org/georss"
namespace gml = "http://www.opengis.net/gml"
namespace openSearch = "http://a9.com/-/spec/opensearchrss/1.0/"

start = personFeed | personEntry


# Describes a People profile feed

personFeed =
  element atom:feed {
    ( element atom:author { personConstruct }+
    & personEntry*
    & generator
    & id
    & itemsPerPage?
    & peopleLink*
    & startIndex?
    & element atom:title { textConstruct }
    & totalResults?
    & updated
    )
  }


# Describes the generator

generator =
  element atom:generator {
    attribute uri { xsd:string }?
    , attribute version { xsd:string }?
    , xsd:string
  }


# Describes a unique identifier

id =
  element atom:id {
    xsd:string
  }


# Describes the number of items that will be returned per page for paged feeds

itemsPerPage =
  element openSearch:itemsPerPage {
    xsd:int
  }


# Describes a person construct used for authors and contributors

personConstruct =
    attribute xml:lang { xsd:string }?
    , ( email?
    & name
    & uri?
    )


# Describes an author's email address

email =
  element atom:email {
    xsd:string
  }


# Describes an author's human-readable name

name =
  element atom:name {
    xsd:string
  }


# Describes the starting index of the contained entries for paged feeds

startIndex =
  element openSearch:startIndex {
    xsd:int
  }


# Describes a text construct containing either plain text, HTML, or XHTML

textConstruct =
    attribute xml:lang { xsd:string }?
    , attribute type { xsd:string }?
    , xsd:string


# Describes the total number of results associated with this feed

totalResults =
  element openSearch:totalResults {
    xsd:int
  }


# Describes a last updated timestamp

updated =
  element atom:updated {
    (xsd:date | xsd:dateTime)
  }


# Describes the URI associated with an author

uri =
  element atom:uri {
    xsd:string
  }


# Extends the base Link class with People extensions

peopleLink =
  element atom:link {
    attribute href { xsd:string }
    , attribute rel { xsd:string }?
    , attribute type { xsd:string }?
  }


# Describes an People profile entry

personEntry =
  element atom:entry {
    ( gdEmail*
    & extendedProperty*
    & geoRssWhere?
    & id
    & im*
    & peopleLink*
    & phoneNumber*
    & postalAddress*
    & element atom:title { textConstruct }
    & updated
    )
  }


# Stores a limited amount of custom data as an auxiliary property of the
#    enclosing entity

extendedProperty =
  element gd:extendedProperty {
    attribute name { xsd:string }
    , attribute value { xsd:string }
  }


# Describes an email address

gdEmail =
  element gd:email {
    attribute address { xsd:string }
    , attribute label { xsd:string }?
    , attribute rel { "home" | "other" | "work" }?
  }


# Describes a geographical location or region

geoRssWhere =
  element georss:where {
    gmlPoint?
  }


# Describes a particular geographical point

gmlPoint =
  element gml:Point {
    gmlPos?
  }


# Describes a latitude and longitude

gmlPos =
  element gml:pos {
    xsd:string?
  }


# Describes an instant messaging address

im =
  element gd:im {
    attribute address { xsd:string }
    , attribute label { xsd:string }?
  }


# Describes a phone number

phoneNumber =
  element gd:phoneNumber {
    attribute label { xsd:string }?
    , attribute rel { "fax" | "home" | "home_fax" | "mobile" | "other" | "pager"
        | "work" | "work_fax" }?
    , xsd:string
  }


# Describes a postal address

postalAddress =
  element gd:postalAddress {
    attribute label { xsd:string }?
    , attribute rel { "home" | "other" | "work" }?
    , xsd:string
  }

Back to top