URL Lookup API Reference

Introduction

We provide a lookup API so that applications can submit URLs that have been shortened with v.gd and get the original long URLs back. If you're looking for documentation on how to shorten URLs using v.gd programmatically please see our URL shortening API reference instead.

Please pay particular attention to the section on API restrictions and limitations when deciding if v.gd is suitable for your application. Our API is primarily intended for low volume applications or applications that run on the machine of an end user (including browser plugins etc.) Our per IP rate limits may make it unsuitable for some server apps that would make very heavy usage of our API and resources.

All of our examples below assume the use of HTTPS GET. For POST the same parameter names are used and they have exactly the same functions, but they must be submitted in the body of the request instead of in the URL which is beyond the scope of this document.

Accessing the API

Our URL lookup API is accessed at https://v.gd/forward.php. You add parameters to this URL depending on the options and functionality you want to use. At a minimum, you need to specify the shortened URL you want to look up, so would access a URL like https://v.gd/forward.php?shorturl=example. A more complex example showing all the possible parameters that can be specified is https://v.gd/forward.php?format=json&callback=myfunction&shorturl=example.

Parameters

format (optional)

The format parameter determines what format v.gd uses to send output back to you (to tell you where the URL you submitted goes or if an error has occurred). Possible values are: -

shorturl (required)

The shorturl parameter is the shortened v.gd URL that you want to look up. You can either submit the full address (e.g. https://v.gd/forward.php?shorturl=https://v.gd/example) or only the unique part (e.g. https://v.gd/forward.php?shorturl=example). The address you submit should be properly formed; the API lookup function is not guaranteed to handle malformed URLs the same way as when you visit them manually.

callback (optional, only used with format=json)

The callback parameter is used to specify a callback function to wrap the returned data in when using JSON format. This can be useful when working with cross domain data. Even when using JSON format this parameter is optional.

Examples of responses in different formats

Here are examples of a success response and error response in the various supported formats so you can see what your application will need to parse.

web

This format returns the standard v.gd URL forwarding webpage in XHTML format as if you had visited the shortened URL in your browser. The HTTP status code of the response is always 200 if the link exists, but is 404 if it doesn't. Any error is described on the webpage.

simple - success

A successful URL creation will give a single line of output in plain text giving the destination of the link you submitted. This will be similar to: -

https://www.example.com/blah

The HTTP status code of the response will be 200.

simple - error

For any error the body of the response will contain a single line of plain text which will always start with "Error: " followed by a description of the actual error that has occurred. An example would be: -

Error: Sorry, we couldn't find the shortened URL you requested. The link you followed may be invalid, or an evil wizard may have cast a spell on our servers.

The HTTP status code of the response varies depending on the class of error that occurred (see section on error codes): -

xml - success

A successful URL creation will return an XML document in the following format where the link's destination is given between "url" tags: -

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><output><url>https://www.example.com/blah</url></output>
xml - error

For any error the XML response will contain the error code between "errorcode" tags and an appropriate message describing the error between "errormessage" tags.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><output><errorcode>2</errorcode><errormessage>The requested shortened URL has been disabled. It may have been used abusively or in violation of our terms.</errormessage></output>
json - success

A successful URL lookup will return a JSON document similar to the following: -

{ "url": "https://www.example.com/blah" }

If you specified the callback parameter this output will be wrapped in a function, e.g. if the callback was set to "myfunc" the response would be: -

myfunc({ "url": "https://www.example.com/blah" });
json - error

For any error the JSON response will contain the error code and an appropriate error message. It will be similar to the following: -

{ "errorcode": 1, "errormessage": "Sorry, we couldn't find the shortened URL you requested. The link you followed may be invalid, or an evil wizard may have cast a spell on our servers." }

Or if the callback parameter was set to "myfunc" as above, the response would be: -

myfunc({ "errorcode": 1, "errormessage": "Sorry, we couldn't find the shortened URL you requested. The link you followed may be invalid, or an evil wizard may have cast a spell on our servers." });

Interpreting error codes

As you'll have seen from the examples above, v.gd returns different error codes for different classes of error that might occur. For the lookup API the meanings of these are: -

Regardless of the format used you always get an error message giving a more specific description of the problem in addition to these codes.

API restrictions/limitations

Our API is subject to the same terms and conditions as any other usage of v.gd. We don't expect authors to take responsibility for the actions of end-users of their apps, but an application shouldn't appear to endorse or be solely designed to do something that's against our terms.

API users should open a maximum of 5 connections to v.gd at any one time.

Access to our API is rate limited to make sure usage doesn't exceed levels that we consider reasonable. Please see our usage limits page to check the current limits. If your application is exceeding our rate limit and receives an error code 3 response (or an HTTP status code of 502 which is the equivalent when using simple format) it should wait a reasonable period such as 1 minute before making any further requests. Machines that continue to hammer us with requests regardless risk being banned.

API best practices