Log In to Shorten a URL

Go.USA.gov API Documentation

The Go.USA.gov API can

  • Shorten a URL
  • Preview the destination of a short URL
  • Get the number of clicks on a short URL

On this page you can find details about how to use the API, including these topics:

See other USA.gov APIs and resources for developers.

Accessing the API

To use the Go.USA.gov API, you must have an account. All registered users are automatically issued an API key.

To find your API key, login to Go.USA.gov and click on your username in the upper-right corner of the screen. You can view and reset your API key.

All API calls take the following form: http://go.usa.gov/api/{method_name}.{result_format_desired}?login={user_name}&apiKey={api_key}&{paramaters_for_api_methd}

Please note: The URLs used in these examples contain a fake username and API key. They will not return results.

By accessing the API, you agree to our terms of use.

API Result Formats

The API can provide results in four formats:

  • JSON (use {method_name}.json)
  • JSONP (use {method_name}.jsonp)
  • XML (use {methond_name}.xml)
  • Plain text (use {method_name}.txt)

For example, a call to the expand method to show the destination of the short URL and returns results in json might look like: http://go.usa.gov/api/expand.json?login=test&apiKey=770915505bafb779557abb98dec929dc&shortUrl=http%3A%2F%2Fgo.usa.gov%2FW3H

If you wanted the same results but in xml format, change it to: http://go.usa.gov/api/expand.xml?login=test&apiKey=770915505bafb779557abb98dec929dc&shortUrl=http%3A%2F%2Fgo.usa.gov%2FW3H

When requesting JSONP results, you should pass in an additional callback parameter to set the name of the callback function that will be used: http://go.usa.gov/api/expand.jsonp?login=test&apiKey=770915505bafb779557abb98dec929dc&shortUrl=http%3A%2F%2Fgo.usa.gov%2FW3H&callback=callback_me

API Return Status Codes

  • 200 - OK
  • 202 - Please provide a longUrl
  • 205 - Please provide a shortUrl
  • 1102 - Invalid login ID
  • 1105 - Invalid API key
  • 1207 - URL you tried to shorten is not a government URL
  • 1213 - We could not find a long URL for that short URL
  • 1214 - URL you tried to shorten was already a short Go.USA.gov URL (note that this status code will also return the Go.USA.gov shortened URL that already exists)

API Methods

Shorten Method: Shortening a URL

Parameters

The shorten method requires the following parameters in addition to login and apiKey:

  • longURL - The encoded long URL that you wish to shorten (such as http%3A%2F%2Fwww.tsa.gov%2Fpress%2Fhappenings%2Fsimplifying_laptop_bag_procedures.shtm instead of http://www.tsa.gov/press/happenings/simplifying_laptop_bag_procedures.shtm)

Results

The shorten method will return:

  • A status code
  • The new short URL
  • The long URL

Sample Calls and Responses

Call:

https://go.usa.gov/api/shorten.json?login=test&apiKey=770915505bafb779557abb98dec929dc&longUrl=http%3A%2F%2Fwww.tsa.gov%2Fpress
%2Fhappenings%2Fsimplifying_laptop_bag_procedures.shtm

Response:

{
  "response": {
    "0": [
    {
      "status_code": "200",
      "status_txt": "OK"
    }],
    "data": {
      "entry": [
      {
        "short_url": "http://go.usa.gov/rKJd",
        "long_url": "http://www.tsa.gov/press/happenings/simplifying_laptop_bag_procedures.shtm"
      }]
    }
  }
}

Call:

https://go.usa.gov/api/shorten.xml?login=test&apiKey=770915505bafb779557abb98dec929dc
&longUrl=http%3A%2F%2Fwww.tsa.gov%2Fpress%2Freleases%2Findex.shtm

Response:

<result>
  <response>
    <item is_array="true">
      <item>
        <status_code>200</status_code>
        <status_txt>OK</status_txt>
      </item>
    </item>
    <data>
      <entry is_array="true">
        <item>
          <short_url>http://go.usa.gov/rKJF</short_url>
          <long_url>http://www.tsa.gov/press/releases/index.shtm\</long_url>
        </item>
      </entry>
    </data>
  </response>
</result>

Call:

https://go.usa.gov/api/shorten.txt?login=test&apiKey=770915505bafb779557abb98dec929dc
&longUrl=http%3A%2F%2Fwww.tsa.gov%2Fpress%2Frss%2Findex.shtm

Response:

200 OK 
http://go.usa.gov/rKS3 http://www.tsa.gov/press/rss/index.shtm

Call:

https://go.usa.gov/api/shorten.jsonp?login=test&apiKey=770915505bafb779557abb98dec929dc&longUrl=
http%3A%2F%2Fwww.tsa.gov%2Fpress%2FSignificantTravelDays%2Findex.shtm&callback=comeBackToMe

Response:

comeBackToMe(
{
  "response": {
    "0": [
    {
      "status_code": "200",
      "status_txt": "OK"
    }],
    "data": {
      "entry": [
      {
        "short_url": "http://go.usa.gov/rKST",
        "long_url": "http://www.tsa.gov/press/SignificantTravelDays/index.shtm"
      }]
    }
  }
});

Expand Method: Preview the Destination of a Short URL

Parameters

The expand method requires the following parameters in addition to login and apiKey:

  • shortUrl  - The encoded shortened URL (such as http%3A%2F%2Fgo.usa.gov%2FW3H instead of http://go.usa.gov/W3H)

Results

The expand method will return:

  • A status code from the list above
  • The short URL
  • The long URL

Sample Calls and Responses

Call:

https://go.usa.gov/api/expand.json?login=test&apiKey=770915505bafb779557abb98dec929dc
&shortUrl=http%3A%2F%2Fgo.usa.gov%2FW3H

Response:

{
  "response": {
    "0": [
    {
      "status_code": "200",
      "status_txt": "OK"
    }],
    "data": {
      "entry": [
      {
        "short_url": "http://go.usa.gov/W3H",
        "long_url": "http://hurricanes.gov/nhc_storms.shtml"
      }]
    }
  }
}

Call:

https://go.usa.gov/api/expand.xml?login=test&apiKey=770915505bafb779557abb98dec929dc
&shortUrl=http%3A%2F%2Fgo.usa.gov%2FW3H

Response:

<result>
  <response>
    <item is_array="true">
      <item>
        <status_code>200</status_code>
        <status_txt>OK</status_txt>
      </item>
    </item>
    <data>
      <entry is_array="true">
        <item>
          <short_url>http://go.usa.gov/W3H</short_url>
          <long_url>http://hurricanes.gov/nhc_storms.shtml</long_url>
        </item>
      </entry>
    </data>
  </response>
</result>

Call:

https://go.usa.gov/api/expand.jsonp?login=test&apiKey=770915505bafb779557abb98dec929dc
&shortUrl=http%3A%2F%2Fgo.usa.gov%2FW3H&callback=comeBackToMe

Response:

comeBackToMe(
{
  "response": {
    "0": [
    {
      "status_code": "200",
      "status_txt": "OK"
    }],
    "data": {
      "entry": [
      {
        "short_url": "http://go.usa.gov/W3H",
        "long_url": "http://hurricanes.gov/nhc_storms.shtml"
      }]
    }
  }
});

Call:

https://go.usa.gov/api/expand.txt?login=test&apiKey=770915505bafb779557abb98dec929dc
&shortUrl=http%3A%2F%2Fgo.usa.gov%2FW3H

Response:

200 OK 
http://go.usa.gov/W3H http://hurricanes.gov/nhc_storms.shtml

Clicks Method: Get the Number of Clicks on a Short URL

The clicks method requires the following parameters in addition to login and apiKey:

Parameters

  • shortUrl - The encoded shortened URL (such as http%3A%2F%2Fgo.usa.gov%2Fjmo instead of http://go.usa.gov/jmo)

Results

  • A status code from the list above
  • The short URL
  • The number of clicks on the short URL

Sample Calls and Responses

Call:

https://go.usa.gov/api/clicks.json?login=test&
apiKey=770915505bafb779557abb98dec929dc&shortUrl=http%3A%2F%2Fgo.usa.gov%2Fjmo

Response:

{
  "response": {
    "0": [
    {
      "status_code": "200",
      "status_txt": "OK"
    }],
    "data": {
      "entry": [
      {
        "short_url": "http://go.usa.gov/jmo",
        "user_clicks": "56199"
      }]
    }
  }
}

Call:

https://go.usa.gov/api/clicks.xml?login=test&apiKey=770915505bafb779557abb98dec929dc
&shortUrl=http%3A%2F%2Fgo.usa.gov%2Fjmo

Response:

<result>
  <response>
    <item is_array="true">
      <item>
        <status_code>200</status_code>
        <status_txt>OK</status_txt>
      </item>
    </item>
    <data>
      <entry is_array="true">
        <item>
          <short_url>http://go.usa.gov/jmo</short_url>
          <user_clicks>56199</user_clicks>
        </item>
      </entry>
    </data>
  </response>
</result>

Call:

https://go.usa.gov/api/clicks.jsonp?login=test&apiKey=770915505bafb779557abb98dec929dc
&shortUrl=http%3A%2F%2Fgo.usa.gov%2Fjmo&callback=comeBackToMe

Response:

comeBackToMe(
{
  "response": {
    "0": [
    {
      "status_code": "200",
      "status_txt": "OK"
    }],
    "data": {
      "entry": [
      {
        "short_url": "http://go.usa.gov/jmo",
        "user_clicks": "56199"
      }]
    }
  }
});

Call:

https://go.usa.gov/api/clicks.txt?login=test&apiKey=770915505bafb779557abb98dec929dc
&shortUrl=http%3A%2F%2Fgo.usa.gov%2Fjmo

Response:

200 OK 
http://go.usa.gov/jmo 56199

Call:

https://go.usa.gov/api/clicks.json?login=test&apiKey=770915505bafb779557abb98dec929dc
&shortUrl=http%3A%2F%2Fg.usa.gov%2Fjmol

Response:

{
  "response": {
    "0": [
    {
      "status_code": "200",
      "status_txt": "OK"
    }],
    "data": {
      "entry": [
      {
        "short_url": "http://g.usa.gov/jmol",
        "user_clicks": "ShortUrl does not exist"
      }]
    }
  }
}

Terms of Use

We reserve the right to cancel any API key at any time should we find that the API is being abused and is causing performance issues for the rest of our users. In the event that we feel this step may be warranted, we will make every attempt to contact you prior to canceling the key.

Go.USA.gov is available "as is." We strive to keep the service stable and reliable, but can’t guarantee 100% availability.

By using this API, you agree to these terms and our general terms of service for developers.