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.

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.

Getting started

Creating a Blogger account

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.

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 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:

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.

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.

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.

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.

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):

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.

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.

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.

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).

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.