As of March 30, 2019, the URL shortener was shut down. Please see this blog post for alternatives.

Get Started

Below, we walk you through the steps to interact with the Google URL Shortener API. This is the programmatic side of the web site at To begin, you should read the section on Authentication. After that, you can skip ahead to the section describing whichever action you would like to perform.

Each section contains a brief description, an example, and a link to more detailed information. The examples in this guide all use a REST-style JSON protocol.

The examples use curl and OACurl to show you how to get started interacting with the API quickly, right from the command line. When developing your application, however, feel free to use your preferred HTTP, JSON, and OAuth libraries.

Authorizing requests and identifying your application

Every request your application sends to the Google URL Shortener API needs to identify your application to Google. There are two ways to identify your application: using an OAuth 2.0 token (which also authorizes the request) and/or using the application's API key. Here's how to determine which of those options to use:

  • If the request requires authorization (such as a request for an individual's private data), then the application must provide an OAuth 2.0 token with the request. The application may also provide the API key, but it doesn't have to.
  • If the request doesn't require authorization (such as a request for public data), then the application must provide either the API key or an OAuth 2.0 token, or both—whatever option is most convenient for you.

About authorization protocols

Your application must use OAuth 2.0 to authorize requests. No other authorization protocols are supported. If your application uses Google Sign-In, some aspects of authorization are handled for you.

Authorizing requests with OAuth 2.0

Requests to the Google URL Shortener API for non-public user data must be authorized by an authenticated user.

This process is facilitated with an OAuth client ID.

Get an OAuth client ID

Or create one in the Credentials page.

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:

  1. When your application needs access to user data, it asks Google for a particular scope of access.
  2. Google displays a consent screen to the user, asking them to authorize your application to request some of their data.
  3. If the user approves, then Google gives your application a short-lived access token.
  4. Your application requests user data, attaching the access token to the request.
  5. 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 Google URL Shortener API:

To request access using OAuth 2.0, your application needs the scope information, as well as information that Google supplies when you register your application (such as the client ID and 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 page with libraries and samples for more details.

Acquiring and using an API key

Requests to the Google URL Shortener API for public data must be accompanied by an identifier, which can be an API key or an access token.

Get a Key

Or create one in the Credentials page.

After you have an API key, your application can append the query parameter key=yourAPIKey to all request URLs.

The API key is safe for embedding in URLs; it doesn't need any encoding.


By default, your registered project gets 1,000,000 requests per day for the URL Shortener API (see the Developers console for more details).


Shorten a long URL

The Google URL Shortener API allows you to shorten URLs just as you would on For example, to shorten the URL, send the following request:

Content-Type: application/json

{"longUrl": ""}

For instance, you could issue the following curl command:

curl \
  -H 'Content-Type: application/json' \
  -d '{"longUrl": ""}'

If successful, the response will look like:

 "kind": "urlshortener#url",
 "id": "",
 "longUrl": ""
  • id is the short URL that expands to the long URL you provided. If your request includes an auth token, then this URL will be unique. If not, then it might be reused from a previous request to shorten the same URL.
  • longUrl is the long URL to which it expands. In most cases, this will be the same as the URL you provided. In some cases, the server may canonicalize the URL. For instance, if you pass, the server will add a trailing slash.

Note: An API key is highly recommended.

An auth token is optional for shorten requests. If you provide one, the short URL will be unique, and it will show up in the authenticated user's dashboard at

See the URL insert method in the Reference document for more details.

Expand a short URL

You can call this method to expand any short URL. For example, to expand, send the following request:


For instance, you could issue the following curl command:

curl ''

If successful, the response will look like:

 "kind": "urlshortener#url",
 "id": "",
 "longUrl": "",
 "status": "OK"
  • id is the short URL you passed in.
  • longUrl is the long URL to which it expands. Note that longUrl may not be present in the response, for example, if status is "REMOVED".
  • status is "OK" for most URLs. If Google believes that the URL is fishy, status may be something else, such as "MALWARE".

Of course, you could also just fetch and inspect the Location header in the response, but using the API has two advantages:

  1. It won't update the short URL's click stats, so you can fetch a bunch of long URLs without worrying about messing up analytics.
  2. If the URL fails to redirect (for example, if Google believes it points to malware), you'll get a machine-readable explanation of why.

Note: An API key is highly recommended.

An auth token is not necessary for expand requests.

See the URL get method in the Reference document for more details.

Look up a short URL's analytics

To look up a short URL's analytics, issue an expand request, adding a parameter to ask for additional details. Add &projection=FULL to the API URL, like this:

curl ''

If successful, the response will look like:

 "kind": "urlshortener#url",
 "id": "",
 "longUrl": "",
 "status": "OK",
 "created": "2009-12-13T07:22:55.000+00:00",
 "analytics": {
  "allTime": {
   "shortUrlClicks": "3227",
   "longUrlClicks": "9358",
   "referrers": [ { "count": "2160", "id": "Unknown/empty" } /* , ... */ ],
   "countries": [ { "count": "1022", "id": "US" } /* , ... */ ],
   "browsers": [ { "count": "1025", "id": "Firefox" } /* , ... */ ],
   "platforms": [ { "count": "2278", "id": "Windows" } /* , ... */ ]
  "month": { /* ... */ },
  "week": { /* ... */ },
  "day": { /* ... */ },
  "twoHours": { /* ... */ }
  • created is the time at which this short URL was created. It is specified in ISO 8601.
  • analytics contains all the click statistics, broken down into the various time slices. That is, month will contain click statistics for the past month, and so on. For each time slice, shortUrlClicks and longUrlClicks should be present, but the rest may not be (e.g. if there were no clicks).

To request a subset of the above information, set the projection parameter to ANALYTICS_CLICKS or ANALYTICS_TOP_STRINGS.

Note: An API key is highly recommended.

An auth token is not necessary for analytics requests.

See the URL get method in the Reference document for more details.

Look up a user's history

To fetch a user's history, issue a request like this:

Authorization: /* auth token here */

In order to demonstrate this, we'll use OACurl instead of curl, to automatically generate the right Authorization header. First, we walk OACurl through the OAuth login dance in order to acquire an auth token:

$ oacurl-login --scope

That should launch a browser window asking for permission to authorize OACurl to the Google URL Shortener data on your Google account. Allow it, and this will create an ~/ file containing the OAuth access token and secret. Then, run:

$ oacurl

If successful, the response will look like:

 "totalItems": 72,
 "itemsPerPage": 30,
 "nextPageToken": "2010-09-29T06:59:22.584+00:00",
 "items": [
   "kind": "urlshortener#url",
   "id": "",
   "longUrl": "",
   "status": "OK",
   "created": "2009-12-13T07:22:55.000+00:00",
  } /* , ... */
  • totalItems is an approximate number of items in the user's entire history.
  • nextPageToken is an opaque string you can use to get the next page of history. It looks a lot like an ISO 8601 formatted date right now, but you should not count on that being true. The nextPageToken will be present on all but the last page.
  • items contains the list of entries for the first "page" of the user's history, in order of descending creation time. The values for each entry are the same as specified in the Analytics section.

Note: An API key is highly recommended.

An auth token is necessary in order to look up a user's history.

See the URL list method in the Reference document for more details.

Error responses

If your request does not succeed, the Google URL Shortener API will return an error response. This response will include a status code, a human readable message, and a list of error details.

For example, here's what is returned if you call the shorten method without specifying a long URL:

 "error": {
  "errors": [
    "domain": "global",
    "reason": "required",
    "message": "Required",
    "locationType": "parameter",
    "location": "resource.longUrl"
  "code": 400,
  "message": "Required"
  • reason specifies the error reason. For example, reason will be "required" or "invalid" if some field was missing or malformed.
  • message is a human readable explanation of the error.
  • locationType, if present, specifies what part of the request has an error. Possible values include "parameter" and "header".
  • location, if present, specifies the location in the request that caused the error, e.g. the name of a missing or malformed parameter.
  • code is the HTTP status code of this response.

Note that requests containing JSON content bodies must be accompanied by a Content-Type: application/json request header. If that header is missing or wrong, you will get an error message. For example:

Unsupported content with type: application/x-www-form-urlencoded

Such error messages may not be in JSON format (depending on the provided content type).