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

If you're using the Go.USA.gov API and have feedback or want to tell us about your product, please e-mail us.

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"
      }]
    }
  }
}

Export Method: Get a List of All Short URLs

Parameters

The export method does not require any additional parameters other than the standard login and apiKey parameters.

Results

  • A status code from the list above
  • A list of the short URLs created with the account associated with the API key used, including details about each URL

Sample Calls and Responses

Call:

https://go.usa.gov/api/export.json?login=test&apiKey=770915505bafb779557abb98dec929dc

Response:

{
  "response":{
    "status":[
      {
        "status_code":"200",
        "status_txt":"OK"
      }
    ],
    "data":[
      {
        "shortUrl":"https://go.usa.gov/BAwk",
        "longUrl":"http://www.usa.gov/topics/consumer/complaint.shtml",
        "dateCreated":"2014-02-21",
        "URLtitle":"Filing Consumer Complaints | USA.gov",
        "URLdescription":"",
        "URLkeywords":"",
        "user_clicks":"0",
        "notes":"consumer complaints"
      },
      {
        "shortUrl":"https://go.usa.gov/BANm",
        "longUrl":"http://www.whitehouse.gov",
        "dateCreated":"2014-02-21",
        "URLtitle":"The White House",
        "URLdescription":"",
        "URLkeywords":"President,Barack Obama,White House,United States of America,44th President,White House history,President Obama,Barck,Barek,Barak,Barrack,Barrak,Obma,Barack",
        "user_clicks":"1",
        "notes":""
      }
    ]

Call:

https://go.usa.gov/api/export.xml?login=test&apiKey=770915505bafb779557abb98dec929dc

Response:

<?xml version="1.0" encoding="utf-8"?>
<result>
  <response>
    <status is_array="true">
      <item>
        <status_code>200</status_code>
        <status_txt>OK</status_txt>
      </item>
    </status>
    <data is_array="true">
      <item>
        <shortUrl>https://go.usa.gov/BAwk</shortUrl>
        <longUrl>http://www.usa.gov/topics/consumer/complaint.shtml</longUrl>
        <dateCreated>2014-02-21</dateCreated>
        <URLtitle>Filing Consumer Complaints | USA.gov</URLtitle>
        <URLdescription></URLdescription>
        <URLkeywords></URLkeywords>
        <user_clicks>0</user_clicks>
        <notes>consumer complaints</notes>
      </item>
      <item>
        <shortUrl>https://go.usa.gov/BANm</shortUrl>
        <longUrl>http://www.whitehouse.gov</longUrl>
        <dateCreated>2014-02-21</dateCreated>
        <URLtitle>The White House</URLtitle>
        <URLdescription></URLdescription>
        <URLkeywords>President,Barack Obama,White House,United States of America,44th President,White House history,President Obama,Barck,Barek,Barak,Barrack,Barrak,Obma,Barack</URLkeywords>
        <user_clicks>1</user_clicks>
        <notes></notes>
      </item>
    </data>
  </response>
</result>

Call:

https://go.usa.gov/api/export.jsonp?login=test&apiKey=770915505bafb779557abb98dec929dc&callback=comeBackToMe

Response:

comeBackToMe({
  "response":{
    "status":[
      {
        "status_code":"200",
        "status_txt":"OK"
      }
    ],
    "data":[
      {
        "shortUrl":"https://go.usa.gov/BAwk",
        "longUrl":"http://www.usa.gov/topics/consumer/complaint.shtml",
        "dateCreated":"2014-02-21",
        "URLtitle":"Filing Consumer Complaints | USA.gov",
        "URLdescription":"",
        "URLkeywords":"",
        "user_clicks":"0",
        "notes":"consumer complaints"
      },
      {
        "shortUrl":"https://go.usa.gov/BANm",
        "longUrl":"http://www.whitehouse.gov",
        "dateCreated":"2014-02-21",
        "URLtitle":"The White House",
        "URLdescription":"",
        "URLkeywords":"President,Barack Obama,White House,United States of America,44th President,White House history,President Obama,Barck,Barek,Barak,Barrack,Barrak,Obma,Barack",
        "user_clicks":"1",
        "notes":""
      }
    ]
  }
});

Call:

https://go.usa.gov/api/export.txt?login=test&apiKey=770915505bafb779557abb98dec929dc

Response:

200 OK
https://go.usa.gov/BAwk http://www.usa.gov/topics/consumer/complaint.shtml 2014-02-21 Filing Consumer Complaints | USA.gov 0
consumer complaints https://go.usa.gov/BANS 2014-02-21 0
https://go.usa.gov/BANm http://www.whitehouse.gov 2014-02-21 The White House President,Barack Obama,White House,United States of America,44th President,White House history,President Obama,Barck,Barek,Barak,Barrack,Barrak,Obma,Barack 1

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.