Profile Map Protocol

Jump to:
JSON Profile definitions
Entity escaping
Using index files
Sitemap file location
Informing search engine crawlers

This document describes the schema and protocol for delivering Profile Map data

The ProfileMap protocol format consists of query with RFC 4627 (JSON) formatted results. All data string values must be UTF-8 encoded.

The JSON must:

• Include a id entry for each profile
• Include a display_url entry for each profile
• Include a name child entry for profile

All other tags are optional. Support for these optional tags may vary among search engines. Refer to each search engine's documentation for details.

Sample JSON Profile

The following minimal profile shows some very basic information

{
  "id": "1697bdcdac0431",
  "name": "John Doe",
  "type": "person",
  "display_url": "http://johndoe.example.com/", 
  "modified_date": "2006-11-15"
  "locations": [
    {
      "title": "hometown",
      "coordinates": [-122.083739, 37.423021, 0]
    }
  ],
  "bio_field": "about_me",
  "fields": {
    "about_me": "I like to take long walks on the beach",
    "occupation": "Ambulance Driver"
  }
}

Also see our example with lots of fields.

JSON Profile definition

The available fields are described below.

Back to top

Escaping

Suffixes

As a matter of convention, fields can hint at their interpretation

• _date indicates that the value shoule be considered as an RFC-3339 formatted date time value.
• _url indicates that the value should be considered a URL in RFC-3986 format.

Strings

All strings in your file must be UTF-8 encoded.

Location

Location is a structured field where all elements are optional. This list should be ordered to have most significant location first. For example, if a user has both a "born in" and "current" address, the "current" address should be listed first, and the "born in" would be second.

URLs

In addition, all URLs (including the URL of your Sitemap) must be URL-escaped and encoded by the web server on which they are located. However, if you are using any sort of script, tool, or log file to generate your URLs (anything except typing them in by hand), this is usually already done for you. Please check to make sure that your URLs follow the RFC-3986 standard for URIs, the RFC-3987 standard for URIs. This includes insuring that the URI is 7 bit clean and/or properly escaped.

Full Profile JSON

The following example shows a more detailed Profile in JSON format.

{
  "id": "1697bdcdac0431",
  "name": "John Doe",
  "type": "person",
  "account_name": "johndoe",
  "click_url": "http://johndoe.example.com",
  "alt_url": [
                "http://www.example.com/profiles.jsp?id=371829347",
                "http://profiles.example.com/johndoe"
              ],
  "modified_date": "2006-11-15",
  "locations": [
     {           
       "title": "current digs",
       "country": "US",
       "adminarea": "DC",
       "locality": "Washington",
       "coordinates": [-77.036667, 38.895, 0]
     },
     {           
       "title": "hometown", 
       "country": "US",
       "adminarea": "CA",
       "subadminarea": "Santa Clara",
       "locality": "Mountain View",
       "postalcode": "94043",
       "coordinates": [-122.083739, 37.423021, 0]
     },
     {
       "title": "parents",
       "text": "Alabama, United States"
     }
  ],            
  "friend_count": 27,
  "friends": ["profile:204fea6red022", "profile:430274aec77392"],
  "bio_field": "about_me",
  "birth_date": "1976-10-23",
  "fields": {
    "about_me": "I like to take long walks on the beach",
    "occupation": "Abmulance Driver",
    "movies": "Taxi Driver, Driving Miss Daisy, Gone in 60 seconds",
    "scared_of": "Flashing red lights",
    "comments": [
      {
        "post_date": "2006-10-23T12:32:47Z",
        "text": "Happy birthday man!"
      },
      {
        "post_date": "2006-10-23T11:32:47Z",
        "text": "you rock!"
      }
    ]             
  }
}

Back to top

Using index files (to provide a directory of profiles)

As opposed to traditional sitemap index files where a site can be described as a "static" entity, where there is a core set of documents that is key to have indexed. A social network service will have millions of unique profiles with islands of individuals. Thus the need for a system by which lists of profiles can be delivered to a crawler.

The basic idea is to have a service that given a token delivers a list of URLs back to be added to a crawler queue.

Sample profile session:

GET http://api.example.com/profilemap.jsp       The initial request is to a well know shared URL
<= {
      "type": "index",
      "next": "http://api.example.com/profilemap.jsp?secret=79&t=0&p=0&st=20061115123324",
      "urls": [
              {
                 "id": "1923745",
                 "url": "http://profiles.example.com/profilejson.jsp?id=1",
                 "modified_date": "2006-10-23T12:32:47Z",
              }, {
                 "id": "1239745",
                 "url": "http://profiles.example.com/profilejson.jsp?id=2",
                 "modified_date": "2006-10-23T12:32:17Z",
              }, {
                 "id": "1474725",
                 "url": "http://profiles.example.com/profilejson.jsp?id=3",
                 "modified_date": "2006-10-23T12:32:07Z",
              }
              ...
        ]
   }

GET http://api.example.com/profilemap.jsp?secret=79&t=0&p=0&st=20061115123324
<= {
      "type": "index",
      "next": "http://api.example.com/profilemap.jsp?secret=79&t=0&p=10000&st=20061115123324",
      "urls": [
              {
                 "id": "3927445",
                 "url": "http://profiles.example.com/profilejson.jsp?id=12742",
                 "modified_date": "2006-06-23T12:32:47Z",
              }, {
                 "id": "6a6640f",
                 "url": "http://profiles.example.com/profilejson.jsp?id=12749",
                 "modified_date": "2006-09-23T12:32:17Z",
              }, {
                 "id": "e047274",
                 "url": "http://profiles.example.com/profilejson.jsp?id=12375",
                 "modified_date": "2006-10-03T12:32:07Z",
              }
              ...
        ]
   }

Informing search engine crawlers

While it's useful to have large batch requests, depending on the service it's also useful to potententially add a ping service to your profile edit page. This can be done by pinging the index provider with the URL to the profilejson object.

Sample ping:

  GET http://ping.example.com/url=http:%2F%2Fprofiles.example.com%2Fprofilejson.jsp%3Fid=2

Back to top

Last Updated: 20 June 2007