The Go.USA.gov API can
If you're using the Go.USA.gov API and have questions, 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.
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.
The API can provide results in four formats:
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
Parameters
The shorten method requires the following parameters in addition to login and apiKey:
Results
The shorten method will return:
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"
}]
}
}
});
Parameters
The expand method requires the following parameters in addition to login and apiKey:
Results
The expand method will return:
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
The clicks method requires the following parameters in addition to login and apiKey:
Parameters
Results
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"
}]
}
}
}
Parameters
The export method does not require any additional parameters other than the standard login and apiKey parameters.
Results
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
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.