XML API Overview

This document gives an overview of the Cloud Storage XML API and is intended for developers. It assumes that you are familiar with web programming and you are comfortable creating applications that consume web services through HTTP requests.

As an alternative to creating HTTP requests and parsing responses manually using the XML API, you can use the Cloud Storage Client Libraries, the gsutil tool, or the Cloud Storage UI, Google Cloud Platform Console. If you are looking to store data for a mobile or web application, Firebase SDKs for Cloud Storage are the quickest way to get started.


Cloud Storage XML API is a RESTful interface that lets you manage Cloud Storage data in a programmatic way. As a RESTful API, it relies on method information and scoping information to define the operations to perform:

  • Method information

    You specify the method information with standard HTTP methods, such as DELETE, GET, HEAD, and PUT.

  • Scoping information

    You specify the scoping information with a publicly-accessible endpoint (URI) and various scoping parameters. In this case, the primary scoping parameter is a path to a resource, which consists of an object name and bucket name. Used together, the object name, bucket name, and public URI create a unique URL to a given resource. You use HTTP methods to perform operations on these resources. You can further scope your operations by using HTTP headers and query string parameters.

For detailed programming information about the Cloud Storage XML API, see the Reference Guide.

Access to Cloud Storage through the XML API is useful when you are working with tools and libraries that must work across different storage providers, or when you are migrating from another storage provider to Cloud Storage. In the latter case, you only need to make a few simple changes to your existing tools and libraries to begin sending requests to Cloud Storage. For more information about migrating to Cloud Storage, see Migrating from Amazon S3 to Google Cloud Storage.


In practical terms, the Cloud Storage XML API provides a web interface for making HTTP requests and handling HTTP responses. Each request implements a standard HTTP method. See XML API Reference Methods for a complete list of the HTTP methods that the Cloud Storage XML API supports.

You can use various HTTP request headers with each of these methods. The Cloud Storage XML API supports HTTP/1.1 request headers. It also supports several extension (custom) request headers, which have an x-goog- prefix. Request header requirements vary depending on the kind of request you're making, but a few request headers are required for every request. The following table describes some frequently used request headers, including required headers:

Request Header Description Usage
Authorization The authentication string for requests. Required for all authenticated requests.
Cache-Control The cache control that you want to be used when someone retrieves an object. Optional
Content-Length The size of the request body (excluding headers) in bytes. Required for all PUT and POST requests.
Content-MD5 The MD5 digest of the request body. Cloud Storage can use this to check the integrity of a PUT operation. Optional.
Content-Type The MIME type of the request body, such as application/xml or text/html. Recommended for requests that contain an entity body.
Date The date and time of the request Required for all requests.
Host The URI for the request. Required for all requests.
x-goog-acl The predefined access control list (ACL) that you want to apply to a bucket or object. Optional.
x-goog-project-id The ID of the project you want to use. Required for creating buckets or listing buckets when using the Cloud Storage XML API in non-interoperable use case. Not required when you are using the XML API for interoperability, such as for compatibility with Amazon S3. For more information, see Migrating from Amazon S3 to Google Cloud Storage.

The Cloud Storage XML API also supports several query string parameters, which you can use to scope your requests. The query string parameters follow the HTTP path portion of the request and must be used in the following standard form:


The most frequently-used query string parameters include the following:

  • acl—used with PUT and GET requests to change or apply object or bucket permissions.
  • delimiter—used with list object requests to limit the scope of the returned list.
  • max-keys—used with list object requests to specify the maximum number of objects you want in the returned list.
  • marker—used with list object requests to specify which object you want the returned list to begin with.
  • prefix—used with list object requests to limit the number of objects that are returned in the list to only those with the given prefix.
  • location—used with GET requests to retrieve the geographical location of a bucket.

All requests to Cloud Storage must be authenticated, with the exception of requests made to anonymously accessible objects or buckets. For detailed information about how you set the Authorization headers for Cloud Storage requests, see Authentication.

Most Cloud Storage requests use the following URI for accessing buckets and objects:


You can scope this further by adding a bucket and object to the URI. The resulting URL can take two forms:


You can use the Cloud Storage URI with unsecured requests (HTTP) and secured requests (HTTPS) that use secure sockets layer (SSL) encryption. Cloud Storage also provides other request endpoints, which you must use if you are redirecting a request with a CNAME alias or you are providing authenticated browser downloads. In addition, there are custom endpoints that can be used for just uploading or downloading data. For more information about these additional endpoints, see Request Endpoints.

A typical authenticated Cloud Storage request is shown in the following example. This request retrieves a list of objects that are stored in a bucket named travel-maps. The request limits the list of objects to only those objects that have the prefix /europe/france</code>.

GET /?prefix=/europe/france/ HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 -0800
Content-Length: 0
x-goog-api-version: 2
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg


The Cloud Storage XML API returns standard HTTP/1.1 response headers and several extension (custom) response headers. The response headers vary according to the operation you perform. Some frequently used response headers are listed in the following table:

Response Header Description
Cache-Control The cache control setting for the response.
Content-Length The size of the response body (excluding headers) in bytes.
Content-Type The MIME type of the response body, such as application/xml or text/html.
Date The date and time of the response.
ETag An HTTP 1.1 entity tag, which you can use to determine whether an object has changed.

Responses can also include a status code. Cloud Storage uses the standard HTTP/1.1 status codes. Error responses include an XML document in the response body, which contains information about the error conditions.

A typical Cloud Storage response is shown in the following example. This example is a response to a list bucket request. The bucket name is travel-maps and the request is scoped so that only objects with the prefix /europe/france/ are returned in the list.

HTTP/1.1 200 OK
Content-Length: 4061
Content-Type: application/xml
Date: Wed, 17 Feb 2010 23:31:57 GMT
Cache-Control: private, max-age=0

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.storage.googleapis.com/2010-03-01'>

Send feedback about...

Cloud Storage Documentation