URL Shortener API

Getting Started

Contents

Introduction

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 goo.gl. 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

We recommend using OAuth 2.0 to authorize requests.

The Google URL Shortener 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 and an API key. You can find your application's API key in the Google APIs Console, in the Simple API Access section of the API Access pane.

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.

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 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.
  2. Activate the Google URL Shortener API in the Services pane of the Google APIs Console. (If it isn't listed in the Console, then skip this step.)
  3. When your application needs access to user data, it asks Google for a particular scope of access.
  4. Google displays an OAuth dialog to the user, asking them to authorize your application to request some of their data.
  5. If the user approves, then Google gives your application a short-lived access token.
  6. Your application requests user data, attaching the access token to the request.
  7. 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:

https://www.googleapis.com/auth/urlshortener

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.

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 auth token.

To acquire an API key, visit the APIs Console. In the Services pane, activate the Google URL Shortener API; if the Terms of Service appear, read and accept them.

Next, go to the API Access pane. The API key is near the bottom of that pane, in the section titled "Simple API Access."

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.

Actions

Shorten a long URL

The Google URL Shortener API allows you to shorten URLs just as you would on goo.gl. For example, to shorten the URL http://www.google.com/, send the following request:

POST https://www.googleapis.com/urlshortener/v1/url
Content-Type: application/json

{"longUrl": "http://www.google.com/"}

For instance, you could issue the following curl command:

curl https://www.googleapis.com/urlshortener/v1/url \
  -H 'Content-Type: application/json' \
  -d '{"longUrl": "http://www.google.com/"}'

If successful, the response will look like:

{
 "kind": "urlshortener#url",
 "id": "http://goo.gl/fbsS",
 "longUrl": "http://www.google.com/"
}
  • 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 http://www.google.com, 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 goo.gl.

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


Expand a short URL

You can call this method to expand any goo.gl short URL. For example, to expand http://goo.gl/fbsS, send the following request:

GET https://www.googleapis.com/urlshortener/v1/url?shortUrl=http://goo.gl/fbsS

For instance, you could issue the following curl command:

curl 'https://www.googleapis.com/urlshortener/v1/url?shortUrl=http://goo.gl/fbsS'

If successful, the response will look like:

{
 "kind": "urlshortener#url",
 "id": "http://goo.gl/fbsS",
 "longUrl": "http://www.google.com/",
 "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 http://goo.gl/fbsS 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 'https://www.googleapis.com/urlshortener/v1/url?shortUrl=http://goo.gl/fbsS&projection=FULL'

If successful, the response will look like:

{
 "kind": "urlshortener#url",
 "id": "http://goo.gl/fbsS",
 "longUrl": "http://www.google.com/",
 "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:

GET https://www.googleapis.com/urlshortener/v1/url/history
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 https://www.googleapis.com/auth/urlshortener

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 ~/.oacurl.properties file containing the OAuth access token and secret. Then, run:

$ oacurl https://www.googleapis.com/urlshortener/v1/url/history

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": "http://goo.gl/fbsS",
   "longUrl": "http://www.google.com/",
   "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).

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.