Developer's Guide: Protocol

Important: This is an old version of this page. For the latest version, use the links in the left-side navbar.

The Blogger Data API allows client applications to view and update Blogger content in the form of Google Data API feeds.

Your client application can use the Blogger Data API to create new blog posts, edit or delete existing blog posts, and query for blog posts that match particular criteria.

In addition to providing some background on the capabilities of the Blogger Data API, this document provides examples of basic Data API interactions using raw XML and HTTP. After reading this document, you may want to learn more about interacting with the API using our client libraries by reading the programming-language-specific sections of this developer's guide.

Contents

  1. Audience
  2. Getting started
    1. Creating a Blogger account
  3. Authenticating to the Blogger service
    1. AuthSub proxy authentication
    2. ClientLogin username/password authentication
  4. Retrieving a list of blogs
  5. Creating posts
    1. Publishing a blog post
    2. Creating a draft blog post
  6. Retrieving posts
    1. Retrieving all blog posts
    2. Retrieving posts using query parameters
  7. Updating posts
  8. Deleting posts
  9. Comments
    1. Creating comments
    2. Retrieving comments
    3. Deleting comments
  10. Export format

Audience

This document is intended for programmers who want to write client applications that can interact with Blogger using XML and HTTP.

This document assumes that you understand the general ideas behind the Google Data APIs protocol.

If you're using a UNIX system and you want to try the examples in this document without writing any code, you may find the UNIX command-line utilities curl or wget useful; for more information, see the manual pages for those utilities.

For Blogger Data API reference information, see the Protocol reference guide.

Getting started

Creating a Blogger account

You may want to sign up for a Blogger account for testing purposes. Blogger uses Google Accounts, so if you already have a Google account, you're all set.

Authenticating to the Blogger service

You can access both public and private feeds using the Blogger Data API. Public feeds don't require any authentication, but they are read-only. If you want to modify blogs, then your client needs to authenticate before requesting private feeds. It can authenticate using either of two approaches: AuthSub proxy authentication or ClientLogin username/password authentication.

For more information about authentication with Google Data APIs in general, see the authentication documentation.

Most of the samples in subsequent sections of this document assume you're supplying the appropriate authentication.

AuthSub proxy authentication

AuthSub proxy authentication is used by web applications that need to authenticate their users to Google Accounts. The website operator and the client code don't have access to the username and password for the Blogger user; instead, the client obtains special AuthSub tokens that allow the client to act on a particular user's behalf. For more detailed information, see the AuthSub documentation.

When a user first visits your application, they have not yet been authenticated. In this case, you need to display some information and a link directing the user to a Google page to authenticate your request for access to their blogs.

The following query parameters are included in the AuthSubRequest URL:

next
The URL of the page that Google should redirect the user to after authentication.
scope
Indicates that the application is requesting a token to access Blogger feeds. The scope string to use is http://www.blogger.com/feeds/ (URL-encoded, of course).
secure
Indicates whether the client is requesting a secure token.
session
Indicates whether the token returned can be exchanged for a multi-use (session) token.

The AuthSubRequest URL might look like this:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html

The user follows the link to Google's site and authenticates to their Google Account.

After the user authenticates, the AuthSub system redirects them to the URL you specified in the next query parameter of the AuthSubRequest URL. The AuthSub system appends an authentication token to that URL, as the value of the token query parameter. For example:

http://www.example.com/welcome.html?token=yourAuthToken

This token value represents a single-use AuthSub token. In this example, since session=1 was specified, this token can be exchanged for an AuthSub session token by calling the AuthSubSessionToken service with the single-use token in an Authorization header, as follows:

GET /accounts/AuthSubSessionToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourAuthToken"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

The AuthSubSessionToken service response includes a Token header that contains the session token and an Expiration header that indicates how long the token will remain valid.

Your application can then use the session token value in the Authorization header of subsequent interactions with Blogger.

Here's an example of an HTTP request, containing a non-secure token, that you might send to Blogger:

GET /feeds/blogID/blogs/posts/defaults HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourSessionToken"
User-Agent: Java/1.5.0_06
Host: www.blogger.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

ClientLogin username/password authentication

Use ClientLogin authentication if your client is a standalone, single-user "installed" client (such as a desktop application). To request an authentication token using the ClientLogin mechanism, send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

The POST body should contain a set of query parameters that look like parameters passed by an HTML form, using the application/x-www-form-urlencoded content type. These parameters are:

Email
The user's email address.
Passwd
The user's password.
service
The Blogger service name is blogger. (For other service names, see the service name list.)
accountType
This should always be set to GOOGLE when using the Blogger API. Failure to set this parameter will prevent access by users who also have a G Suite account.
source
Identifies your client application. Should take the form companyName-applicationName-versionID. The examples use the name exampleCo-exampleApp-1.

For more information about the parameters, see the Authentication for Installed Applications document.

If the authentication request fails, then the server returns an HTTP 403 Forbidden status code.

If it succeeds, then the server returns an HTTP 200 OK status code, plus three long alphanumeric codes in the body of the response: SID, LSID, and Auth. The Auth value is the authorization token that you'll send to Blogger with each of your subsequent requests, so keep a copy of that value. You can ignore the SID and LSID values.

Since all requests to private feeds require authentication, you have to set the Authorization header in all subsequent interactions with Blogger, using the following format:

Authorization: GoogleLogin auth=yourAuthToken

Where yourAuthToken is the Auth string returned by the ClientLogin request.

For more information about ClientLogin authentication, including sample requests and responses, see the Authentication for Installed Applications documentation.

Note: Use the same token for all requests in a given session; don't acquire a new token for each Blogger request.

Note: As described in the ClientLogin documentation, the authentication request may fail and request a CAPTCHA challenge. If you want Google to issue and handle the CAPTCHA challenge, then send the user to https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (rather than to the CAPTCHA-handling URL given in the ClientLogin documentation).

Retrieving a list of blogs

The Blogger Data API provides a feed that lists the blogs for a particular user; that feed is known as a "metafeed."

Send an HTTP GET to the following URL to retrieve the list of blogs:

http://www.blogger.com/feeds/userID/blogs

Note: You can also substitute default for the user ID, which tells Blogger to return the list of blogs for the user whose credentials accompany the request.

An entry in the metafeed might look like this:

<entry>
  <id>tag:blogger.com,1999:blog-blogID.post-postID</id>
  <published>2006-08-02T18:44:43.089-07:00</published>
  <updated>2006-11-08T18:10:23.020-08:00</updated>
  <title type='text'>Lizzy's Diary</title>
  <summary type='html'>Being the journal of Elizabeth Bennet</summary>
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/'>
  </link>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default'>
  </link>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='http://www.blogger.com/feeds/blogID/posts/default'>
  </link>
  <link rel='self' type='application/atom+xml'
    href='http://www.blogger.com/feeds/userID/blogs/blogID'>
  </link>
  <link rel='edit' type='application/atom+xml'
      href='http://www.blogger.com/feeds/userID/blogs/blogID'>
  </link>
  <author>
    <name>Elizabeth Bennet</name>
    <email>noreply@blogger.com</email>
    <uri>http://www.blogger.com/profile/profileID</uri>
  </author>
</entry>

For information about what each of those elements means, see the Google Data APIs Protocol Reference document or the Atom 1.0 specification.

If your request fails for some reason, Blogger may return a different status code. More information about HTTP status codes is also available in the Google Data APIs Protocol Reference document.

Creating posts

The Blogger Data API allows you to create and publish new blog entries, as well as creating drafts of entries.

Publishing a blog post

After authenticating, you can publish new blog entries.

First, create an XML representation of the post to publish. This XML needs to be in the form of an Atom <entry> element, which might look like this:

<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Marriage!</title>
  <content type='xhtml'>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>Mr. Darcy has <em>proposed marriage</em> to me!</p>
      <p>He is the last man on earth I would ever desire to marry.</p>
      <p>Whatever shall I do?</p>
    </div>
  </content>
  <category scheme="http://www.blogger.com/atom/ns#" term="marriage" />
  <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Darcy" />
</entry>

Note: Setting a custom author for posts is currently not supported. All new posts will appear as if they were created by the currently authenticated user.

To publish this entry, send it to the blog's post URL as follows. First, place your Atom <entry> element in the body of a new POST request, using the application/atom+xml content type. Then find the blog's post URL in the metafeed by locating the <link> element where the rel attribute ends with #post. The blog's post URL is given as the href attribute of this element, which is in this format:

http://www.blogger.com/feeds/blogID/posts/default

Note: This URL is the same as the URL in the <link rel="service.post"> tag that appears in the <head> section of the human-readable version of the blog.

Blogger creates a blog post using the entry you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new post in the form of an <entry> element. The entry returned is the same one you sent, but it also contains various elements added by Blogger, such as an <id> element.

If your request fails for some reason, Blogger may return a different status code. For information about the status codes, see the Google Data API protocol reference document.

Creating a draft blog post

Draft posts are created in the same way as public posts, but with an <app:control> element added to the entry indicating that the post shouldn't (yet) be published.

This <app:control> element should contain a single <app:draft> element as a child:

<app:control xmlns:app='http://purl.org/atom/app#'>
  <app:draft>yes</app:draft>
</app:control>

The data contained in the <app:draft> element must be the string yes in order for the post to be recognized as a draft.

You can turn an existing draft blog post into a published post by retrieving the draft post, setting the <app:draft> element's data to the string no, and then updating the post. Retrieving and updating posts is covered in the next two sections.

Note: For more information on the Atom Publishing Protocol, including the <app:control> and <app:draft> namespaces, see RFC 5023.

Retrieving posts

The following sections describe how to retrieve a list of blog posts, with and without query parameters.

You can query a Blogger public feed without authentication. Therefore, you don't need to set the Authorization parameter when you retrieve blog posts from a public blog.

Retrieving all blog posts

To retrieve the user's posts, send an HTTP GET request to the blog's feed URL. Blogger then returns a feed containing the appropriate blog entries. For example, to get a list of blog posts for liz@gmail.com, send the following HTTP request to Blogger (with the appropriate value in place of blogID, of course):

GET http://www.blogger.com/feeds/blogID/posts/default

Blogger then returns an HTTP 200 OK status code and a standard Atom 1.0 feed containing the blog posts.

The following is an example of a feed for a blog with only one post. Notice that we've slightly edited this example to make it a little more readable by humans. In particular, a real Blogger feed contains actual IDs and URLs.

<feed xmlns='http://www.w3.org/2005/Atom'>
  <id>tag:blogger.com,1999:blog-blogID</id>
  <updated>2006-11-08T18:10:23.020-08:00</updated>
  <title type='text'>Lizzy's Diary</title>
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/index.html'>
  </link>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default'>
  </link>
  <link rel='self' type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default'>
  </link>
  <author>
    <name>Elizabeth Bennet</name>
    <email>noreply@blogger.com</email>
    <uri>http://www.blogger.com/profile/profileID</uri>
  </author>
  <generator version='7.00' uri='http://www2.blogger.com'>Blogger</generator>
  <entry>
    <id>tag:blogger.com,1999:blog-blogID.post-postID</id>
    <published>2006-11-08T18:10:00.000-08:00</published>
    <updated>2006-11-08T18:10:14.954-08:00</updated>
    <title type='text'>Quite disagreeable</title>
    <content type='html'>&lt;p&gt;I met Mr. Bingley's friend Mr. Darcy
      this evening. I found him quite disagreeable.&lt;/p&gt;</content>
    <link rel='alternate' type='text/html'
      href='http://blogName.blogspot.com/2006/11/quite-disagreeable.html'>
    </link>
    <link rel='self' type='application/atom+xml'
      href='http://blogName.blogspot.com/feeds/posts/default/postID'>
    </link>
    <link rel='edit' type='application/atom+xml'
      href='http://www.blogger.com/feeds/blogID/posts/default/postID'>
    </link>
    <author>
      <name>Elizabeth Bennet</name>
      <email>noreply@blogger.com</email>
      <uri>http://www.blogger.com/profile/profileID</uri>
    </author>
  </entry>
</feed>

Retrieving posts using query parameters

The Blogger Data API lets you request a set of entries that match specified criteria, such as requesting blog posts published or updated in a given date range.

For example, to send a date-range query, add the published-min and published-max parameters to the request URL. To get all the blog entries created between March 16, 2008 to March 24, 2008, send an HTTP request to the blog's feed URL:

GET http://www.blogger.com/feeds/blogID/posts/default?published-min=2008-03-16T00:00:00&published-max=2008-03-24T23:59:59

When you send that GET request, Blogger returns an HTTP 200 OK status code and a feed containing any blog posts that were created in the date range you specified.

The updated-min and updated-max parameters may also be used to get all the blog entries updated within a given range. However, note that these parameters are ignored unless the orderby parameter is also set to updated.

The Blogger Data API supports the following query parameters:

alt
The type of feed to return, such as atom (the default) or rss.
/category
Specifies categories (also known as labels) to filter the feed results. For example, http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie returns entries with both the labels Fritz and Laurie.
max-results
The maximum number of entries to return.
orderby
The order in which to return entries, such as lastmodified (the default), starttime, or updated.
published-min, published-max
The bounds on entry publication dates.
start-index
The 1-based index of the first result to be retrieved (for paging).
updated-min, updated-max
The bounds on entry update dates. These query parameters are ignored unless the orderby parameter is set to updated.

For more information about query parameters, see the Blogger Data API Reference Guide and the Google Data APIs Reference Guide.

Updating posts

To update an existing blog post, first you retrieve the entry you want to update, then you modify it, and then you send a PUT request, with the updated entry in the message body, to the post's edit URL. Be sure that the <id> value in the entry you PUT exactly matches the <id> of the existing entry.

The edit URL is highlighted in the following entry:

<entry>
  <id>tag:blogger.com,1999:blog-blogID.post-postID</id>
  <published>2006-11-08T18:10:00.000-08:00</published>
  <updated>2006-11-08T18:10:14.954-08:00</updated>
  <title type='text'>Quite disagreeable</title>
  <content type='html'>&lt;p&gt;I met Mr. Bingley's friend Mr. Darcy
    this evening. I found him quite disagreeable.&lt;/p&gt;</content>
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/2006/11/quite-disagreeable.html'>
  </link>
  <link rel='self' type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default/postID'>
  </link>
  <link rel='edit' type='application/atom+xml'
    href='http://www.blogger.com/feeds/blogID/posts/default/postID'>
  </link>
  <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Bingley" />
  <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Darcy" />
  <author>
    <name>Elizabeth Bennet</name>
    <email>noreply@blogger.com</email>
    <uri>http://www.blogger.com/profile/profileID</uri>
  </author>
</entry>

IMPORTANT: To ensure forward compatibility, be sure that when you PUT an updated entry, you preserve all the XML that was present when you retrieved the entry from Blogger. Otherwise, when we implement new stuff and include <new-awesome-feature> elements in the feed, your client won't return them and your users will miss out. The Google Data API client libraries all handle this correctly, so if you're using one of the libraries you're all set.

Note: Modifying the author data associated with posts is currently not supported.

Troubleshooting Tip: Some firewalls block HTTP PUT messages. To get around this, you can include a X-HTTP-Method-Override: PUT header in a POST request. For details, see the Google Data API protocol basics document.

Deleting posts

To delete a post, send a DELETE request to the post's edit URL. This is the same URL used to update posts.

Troubleshooting Tip: Some firewalls block HTTP DELETE messages. To get around this, you can include a X-HTTP-Method-Override: DELETE header in a POST request. For details, see the Google Data API protocol basics document.

Comments

The Blogger Data API allows for creating, retrieving, and deleting comments. Updating comments is not supported (nor is it available in the web interface).

Creating comments

To post a comment, create an Atom <entry> element like the following:

  <entry xmlns='http://www.w3.org/2005/Atom'>
    <title type="text">This is my first comment</title>
    <content type="html">This is my first comment</content>
  </entry>

To publish this comment, place your Atom <entry> element in the body of a new POST request, using the application/atom+xml content type. Then send the POST request to the appropriate Blogger URL:

POST http://www.blogger.com/feeds/blogID/postID/comments/default

Note: Currently, you can only post comments to a blog owned by the authenticated user.

Note: Setting a custom author for comments is currently not supported. All new comments will appear as if they were created by the currently authenticated user.

Retrieving comments

You can retrieve the comments for a particular post by sending a GET to this post's comments feed URL:

GET http://www.blogger.com/feeds/blogID/postID/comments/default

Or you can get the comments from all posts by using the blog's comments feed URL:

GET http://www.blogger.com/feeds/blogID/comments/default

These requests return a comments feed that looks like this:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
         xmlns:thr="http://purl.org/syndication/thread/1.0">
  <id>tag:blogger.com,1999:blog-blogID.post-postID.comment-commentID</id>
  <updated>2007-04-04T21:56:29.803-07:00</updated>
  <title type="text">My Blog : Time to relax</title>
  <link rel="alternate" type="text/html" href="http://blogName.blogspot.com/2007/04/first-post.html"/>
  <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="http://blogName.blogspot.com/feeds/postID/comments/default"/>
  <link rel="self" type="application/atom+xml" href="http://blogName.blogspot.com/feeds/postID/comments/default"/>
  <author>
    <name>Blog Author name</name>
  </author>
  <generator version="7.00" uri="http://www2.blogger.com">Blogger</generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <entry>
    <id>tag:blogger.com,1999:blog-blogID.post-commentID</id>
    <published>2007-04-04T21:56:00.000-07:00</published>
    <updated>2007-04-04T21:56:29.803-07:00</updated>
    <title type="text">This is my first comment</title>
    <content type="html">This is my first comment</content>
    <link rel="alternate" type="text/html" href="http://blogName.blogspot.com/2007/04/first-post.html#commentID"/>
    <link rel="self" type="application/atom+xml" href="http://blogName.blogspot.com/feeds/postID/comments/default/commentID"/>
    <link rel="edit" type="application/atom+xml" href="http://www.blogger.com/feeds/blogID/postID/comments/default/commentID"/>
    <thr:in-reply-to href="http://blogName.blogspot.com/2007/04/first-post.html" 
                     ref="tag:blogger.com,1999:blog-blogID.post-postID" 
                     source="http://www.blogger.com/feeds/posts/default/blogID"
                     type="text/html"/>
    <author>
      <name>Blog Author name</name>
      <email>blog_author@gmail.com</email>
      <uri>http://www.blogger.com/profile/userID</uri>
    </author>
    <thr:in-reply-to xmlns:thr='http://purl.org/syndication/thread/1.0' 
         href='http://blogName.blogspot.com/2007/04/first-post.html' 
         ref='tag:blogger.com,1999:blog-blogID.post-postID' 
         source='http://blogName.blogspot.com/feeds/posts/default/postID'
         type='text/html' />
  </entry>
</feed>

Deleting comments

To delete a comment, send a DELETE request to the comment's edit URL. This URL is highlighted in the comments feed above.

Export format

Blogger allows users to export and import their blogs using a Blogger export file. This export file contains all of the posts and comments for one blog. The format for the export file is the exact same Atom format that is described in the sections on retrieving posts and comments. This export file will contain the contents of the post feed and the contents of the comments feed combined into one document.

To export or import blog data using the export format, you can visit the Settings page for the blog. To retrieve the export file for a blog using the Data API, use the following URL:

GET http://www.blogger.com/feeds/blogID/archive

To import the export file, create a POST request to the following URL with the contents of the export file as the request data and application/atom+xml as the content type:

POST http://www.blogger.com/feeds/blogID/archive/full

Neither of the URLs for above support query parameters. Both requests must also contain authentication information and only blog administrators will be able to import/export the blog using these feed URLs.

Note: If you are creating your own Blogger export file, there is currently one restriction around the ordering of the post and comment entries. The Blogger export file will list all of the posts first, and then all of the comments. Interleaving post and comment entries is allowed so long as the comment entry comes after the post the comment is for.

For more information about how Blogger uses the Atom format in the export file, see the Protocol reference guide.

Back to top