LongURL REST API

LongURL provides a simple REST API to allow application developers to easily use its service.

If you're gonna use our API, ! We'd love to hear what you're up to. Also, please set a descriptive user-agent to help us perform better monitoring of the service.

API Endpoint URL

API requests must be sent to the api sub-domain. They must also reference an API version in the first URL segment followed by the application resource.

Example: http://api.longurl.org/v1/services

Expand URL

The primary function LongURL provides is expanding shortened URLs to their long equivalent.

Example: http://api.longurl.org/v1/expand?url=http://short.com/123

List Known Services

If you'd like, you can also get a list of known shortening services along with the domains they use. We support all services (even ones not on the list), but these are just the ones we know of.

Example: http://api.longurl.org/v1/services

Example XML Response

<response>
	<services>
		<service>
			<name>tinyurl.com</name>
			<domain>tinyurl.com</domain>
		</service>
		<service>
			<name>is.gd</name>
			<domain>is.gd</domain>
		</service>
		<service>
			<name>bit.ly</name>
			<domain>bit.ly</domain>
		</service>
		<service>
			<name>snipurl.com</name>
			<domain>snipurl.com</domain>
			<domain>snurl.com</domain>
			<domain>snipr.com</domain>
		</service>
		<service>
			<name>ping.fm</name>
			<domain>ping.fm</domain>
		</service>
		<service>
			<name>metamark.net</name>
			<domain>xrl.us</domain>
		</service>
	</services>
</response>

Response Formats

LongURL supports three response formats: XML, JSON, and PHP (serialized). To specify a response format other than XML (the default), use the format argument.

Example: http://api.longurl.org/v1/expand?url=http://short.com/123&format=[xml|json|php]

Example XML Response

Success:

<response>
	<long_url>http://example.com</long_url>
</response>

Error:

<response>
	<messages>
		<error>Unsupported service.</error>
	</messages>
</response>

Example JSON Response

Success:

{
	"long_url":"http:\/\/google.com"
}

Error:

{
	"messages":[
		{
			"message":"Unsupported service.",
			"type":"error"
		}
	]
}

When using the JSON response format you can also specify an optional callback function using the callback argument.

Example: http://api.longurl.org/v1/expand?url=http://short.com/123&format=json&callback=foo

Example JSON Response With Callback

Success:

foo({
	"long_url":"http:\/\/google.com"
})

Error:

foo({
	"messages":[
		{
			"message":"Unsupported service.",
			"type":"error"
		}
	]
})

Example PHP Response

Success:

a:1:{
	s:8:"long_url";s:17:"http://google.com";
}

Error:

a:1:{
	s:8:"messages";a:1:{
		i:0;a:2:{
			s:7:"message";s:20:"Unsupported service.";
			s:4:"type";s:5:"error";
		}
	}
}