API Version 2.0 Documentation

LongURL provides a simple RESTful API to allow application developers to easily use its service. This documentation and the API are subject to change. While the API is versioned, early versions of the API my be aggressively deprecated.

Contents

Courteous Usage

  1. Please let us know if you will be releasing software that uses our API as it can help in troubleshooting issues, and hey, we'd like to know what you're up to!
  2. Clients should cache API responses to avoid making repeated requests to our servers for the same content.
  3. It is required that you set an identifiable User-Agent for your application.
  4. All URL argument values should be URL encoded.
  5. Do not make repeated requests containing invalid arguments. (i.e. A valid short URL must begin with http:// or https://)

User-Agents

All requests must include a descriptive User-Agent header. JSONP requests should set a user-agent URL argument instead. Requests that do not include this information may be blocked.

To set the User-Agent in PHP for example, you must modify the user_agent setting in the php.ini file or through ini_set(). E.g.

ini_set('user_agent', 'Application-Name/3.7');

The same thing can be accomplished in Ruby using

open('http://example.com', 'User-Agent' => 'Application-Name/3.7')

API Endpoint

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:

GET http://api.longurl.org/v2/services

List Known Services

LongURL maintains a list of known URL shortening services. This list can—and in most cases should—be used to identify URLs which have been shortened before making a request to the LongURL API. (Note: We support nearly all shortening services (even ones not on the list), but these are just the ones we know of.)

Example:

GET http://api.longurl.org/v2/services

Arguments

format (optional)
Response format. Could be xml (default), json, or php.
callback (optional)
Callback function name. Only used for JSONP. Requires that the format argument be set to json.

Expand URL

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

Example:

GET http://api.longurl.org/v2/expand?url=http%3A%2F%2Fis.gd%2Fw

Arguments

url
The short URL which is to be expanded. The must start with http:// or https://, and should be URL encoded.
all-redirects (optional)
Set value to 1 to include all HTTP redirects in the response. Example
content-type (optional)
Set value to 1 to include the internet media type of the destination URL in the response. Example
response-code (optional)
Set value to 1 to include the HTTP response code of the destination URL in the response. Example
title (optional)
Set value to 1 to include the HTML title of the destination URL in the response (if a web page). Example
rel-canonical (optional)
Set value to 1 to include the canonical URL of the destination URL in the response (if a web page). Example
meta-keywords (optional)
Set value to 1 to include the meta keywords of the destination URL in the response (if a web page). Example
meta-description (optional)
Set value to 1 to include the meta description of the destination URL in the response (if a web page). Example
format (optional)
Response format. Could be xml (default), json, or php.
callback (optional)
Callback function name. Only used for JSONP. Requires that the format argument be set to json.

Response Formats

LongURL supports four response formats: XML, JSON, JSONP, and PHP (serialized). To specify a response format other than XML (the default), use the format argument. (Note: All responses are UTF-8 encoded)

Example:

GET http://api.longurl.org/v2/services&format=json

To get a JSONP response, specify json as the value for the format argument and set the callback argument to your function name. Since a descriptive User-Agent is required, JSONP requests should also include a user-agent argument.

Example:

GET http://api.longurl.org/v2/services&format=json&callback=foo&user-agent=Application-Name%2F3.7

Error Responses

API clients can examine the HTTP response code to identify errors. Below are the response codes that may be encountered. (Note: A 200 response code means there were no errors)

400 Bad Request
Something about your request is wrong. The payload should contain a message with more details.
404 Not Found
You're asking for something that doesn't exist. Perhaps you're using an invalid API version, or requesting a resource that isn't there.
500 Internal Server Error
Something went wrong on our end that prevented us from fulfilling the request.
503 Service Unavailable
Our service is temporarily unable to handle requests. Try again later.
504 Bad Gateway
Something went wrong when the servers tried to talk to each other. This usually happens when a shortening service is down and can not handle requests from our servers.

In the event of an error, the response payload may contain additional information regarding the error.