Important: We will discontinue support for the v2.0 Google Data API on September 30th, 2024. To ensure continued functionality, update your applications that rely on the v2.0 Google Data API to the latest API version. For the latest version, use the links in the left-side navbar. Note: while some GET requests (such as listing posts) will continue to be supported as feed URLs, there are minor differences in their behavior. For detailed information, refer to the Blogger Help documentation.
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 HTTPS. 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
Audience
This document is intended for programmers who want to write client applications that can interact with Blogger using XML and HTTPS.
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.
Authorizing requests
When your application requests non-public user data, it must include an authorization token. The token also identifies your application to Google.
About authorization protocols
We recommend using OAuth 2.0 to authorize requests.
The Blogger GData API also supports older authorization options, such as OAuth 1.0, AuthSub, or ClientLogin; however, in most cases we don't recommend using those other options. If your application already uses those options, we recommend migrating to OAuth 2.0 if possible.
If your application has certain unusual authorization requirements, such as logging in at the same time as requesting data access (hybrid) or domain-wide delegation of authority (2LO), then you cannot currently use OAuth 2.0 tokens. In such cases, you must instead use OAuth 1.0 tokens.
Authorizing requests with OAuth 2.0
Requests to the Blogger GData API for non-public user data must be authorized by an authenticated user.
The details of the authorization process, or "flow," for OAuth 2.0 vary somewhat depending on what kind of application you're writing. The following general process applies to all application types:
- When you create your application, you register it with Google. Google then provides information you'll need later, such as a client ID and a client secret.
- When your application needs access to user data, it asks Google for a particular scope of access.
- Google displays an OAuth dialog to the user, asking them to authorize your application to request some of their data.
- If the user approves, then Google gives your application a short-lived access token.
- Your application requests user data, attaching the access token to the request.
- If Google determines that your request and the token are valid, it returns the requested data.
Some flows include additional steps, such as using refresh tokens to acquire new access tokens. For detailed information about flows for various types of applications, see Google's OAuth 2.0 documentation.
Here's the OAuth 2.0 scope information for the Blogger GData API:
https://www.blogger.com/feeds/
To request access using OAuth 2.0, your application needs the scope information, as well as information that Google supplies during application registration (such as the client ID and/or the client secret).
Tip: The Google APIs client libraries can handle some of the authorization process for you. They are available for a variety of programming languages; check the Libraries and Samples page for more details.
Specifying a version
Every request that you send using the Blogger Data API should specify version 2 of the API.
To specify a version number, use the GData-Version
HTTP header:
GData-Version: 2
Alternatively, if you can't set HTTP headers, you can specify
v=2
as a query parameter in the URL. But the HTTP header is
preferred where possible.
Note: The client libraries supply appropriate
version headers automatically, so don't use the v=2
query parameter
when you're using a client library.
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:
https://www.blogger.com/feeds/profileID/blogs
Where the profile ID is the number in the URL for the user's profile page.
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 gd:etag='W/"D08FQn8-eip7ImA9WxZbFEw."'> <id>tag:blogger.com,1999:user-userNumber.blog-blogID</id> <published>2006-08-02T18:44:43.089-07:00</published> <updated>2008-04-17T00:03:33.152-07:00</updated> <title>Lizzy's Diary</title> <summary type='html'>Being the journal of Elizabeth Bennet</summary> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/profileID/blogs/blogID' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/' /> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default' /> <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default' /> ... <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>noreply@blogger.com</email> </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:
https://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://www.w3.org/2007/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 https://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.
<?xml version='1.0' encoding='utf-8'?> <?xml-stylesheet href="http://www.blogger.com/styles/atom.css" type="text/css"?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"D08FQn8-eip7ImA9WxZbFEw."'> <id>tag:blogger.com,1999:blog-blogID</id> <updated>2008-04-17T00:03:33.152-07:00</updated> <title>Lizzy's Diary</title> <subtitle type='html'></subtitle> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default' /> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/' /> <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>noreply@blogger.com</email> </author> <generator version='7.00' uri='http://www2.blogger.com'>Blogger</generator> <entry gd:etag='W/"D0YHRn84eip7ImA9WxZUFk8."'> <id>tag:blogger.com,1999:blog-blogID.post-postID</id> <published>2008-04-07T20:25:00.005-07:00</published> <updated>2008-04-07T20:25:37.132-07:00</updated> <title>Quite disagreeable</title> <content type='html'><p>I met Mr. Bingley's friend Mr. Darcy this evening. I found him quite disagreeable.</p></content> <link rel='edit' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default/postID' /> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default/postID' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/2008/04/quite-disagreeable.html' /> <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>noreply@blogger.com</email> </author> </entry> </feed>
Retrieving a blog post again
If you want to retrieve a post that you've retrieved before, you can improve efficiency by telling Blogger to send the post only if it has changed since the last time you retrieved it.
To do this sort of conditional retrieval, send an HTTP GET
request that includes an HTTP If-None-Match
header. In the header,
specify the entry's ETag, which you can find in the <entry>
element's gd:etag
attribute.
For example:
If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."
When Blogger receives this request, it checks to see whether the entry that
you requested has the same ETag as the ETag you specified. If the ETags match,
then the entry hasn't changed, and Blogger returns an HTTP 304 Not
Modified
status code.
If the ETags don't match, then the entry has been modified since the last time you requested it, and Blogger returns the entry.
For more information about ETags, see the Google Data APIs reference guide.
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 https://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) orrss
. - /category
- Specifies categories (also known as labels) to filter the feed results. For example,
https://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie
returns entries with both the labelsFritz
andLaurie
. - max-results
- The maximum number of entries to return.
- orderby
- The order in which to return entries, such as
lastmodified
(the default),starttime
, orupdated
. - 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 toupdated
. - path
- The permalink path for a post. For example, for a post that has the URL http://buzz.blogger.com/2011/08/bloggers-fresh-new-look.html, the permalink path is
/2011/08/bloggers-fresh-new-look.html
. - q
- Full text query string. This enables you to search a blog for posts that match a query.
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 gd:etag='W/"CUYDSXo8fSp7ImA9WB9UFkU."'> <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'><p>I met Mr. Bingley's friend Mr. Darcy this evening. I found him quite disagreeable.</p></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 https://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 https://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 https://www.blogger.com/feeds/blogID/comments/default
These requests return a comments feed that looks like this:
<?xml version='1.0' encoding='utf-8'?> <?xml-stylesheet href="http://www.blogger.com/styles/atom.css" type="text/css"?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"CUYMQ348fyp7ImA9WB9UFkU."'> <id>tag:blogger.com,1999:blog-blogID.postpostID..comments</id> <updated>2007-12-14T17:46:22.077-08:00</updated> <title>Comments on Lizzy's Diary: Quite disagreeable</title> <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://www.blogger.com/feeds/blogID/postID/comments/default' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html' /> <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>noreply@blogger.com</email> </author> <generator version='7.00' uri='http://www.blogger.com'>Blogger</generator> <openSearch:totalResults>1</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <entry gd:etag='W/"CUYCQX47eSp7ImA9WB9UFkU."'> <id>tag:blogger.com,1999:blog-blogID.post-commentID</id> <published>2007-12-14T17:46:00.001-08:00</published> <updated>2007-12-14T17:46:00.001-08:00</updated> <title>Darcy FTW!</title> <content type='html'>Darcy FTW!</content> <link rel='edit' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/postID/comments/default/commentID' /> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/postID/comments/default/commentID' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html?showComment=1197683160001#ccommentID' title='' /> <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>liz@gmail.com</email> </author> <thr:in-reply-to xmlns:thr='http://purl.org/syndication/thread/1.0' href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html' ref='tag:blogger.com,1999:blog-blogID.post-postID' source='http://www.blogger.com/feeds/blogID/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 https://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 https://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.