Skip to content

Polr PaaS API Documentation

Chaoyi Zha edited this page Sep 5, 2015 · 12 revisions

API Endpoints

All API calls should be directed to /api.php.

API keys

You will need to request an API key in order to use the Polr API at high volume. By default, all users may utilize the public API endpoint (route requests to /publicapi.php rather than /api.php) at a limited rate. If you have an API key, send it as the GET or POST variable apikey. This is required for every API call. If the API key is invalid, the API will return with the status code 401 (Unauthorized).

Request an API key by joining our IRC channel (freenode, #polr), or by emailing us ([email protected]).

Actions

Actions are passed in the GET or POST variable action. There are currently two actions implemented:

  • shorten - shortens a URL
  • lookup - looks up the destination of a shortened URL

Actions take arguments, which are passed as GET or POST parameters.

shorten

The shorten action takes a single argument: url. This is the URL to shorten. The API will return with a plain text response containing a shortened URL.

Example: GET http://polr.me/api.php?apikey=key&action=shorten&url=http://google.com

Remember that the url argument must be urlencoded (unless it is passed as a POST parameter).

lookup

The lookup action takes a single argument: url. This is the URL to lookup. If it exists, the API will return with the destination of that URL. If it does not exist, the API will return with the status code 404 (Not Found).

Example: GET http://polr.me/api.php?apikey=hunter2&action=lookup&url=3

Remember that the url argument must be urlencoded (unless it is passed as a POST parameter).

Response

The API will respond in plain text. For lookup and shorten, it will reply with a URL, e.g http://polr.me/123 or http://alookedupurl.com .

Code Examples

PHP

<?php
$shortenedurl = file_get_contents('http://polr.me/api.php?apikey=key&action=shorten&url=http://google.com');
echo "The shortened version of http://google.com is $shortenedurl";
?>

Python

Use our Python wrapper (by skasturi):

First, install the wrapper through PyPi. pip install polr. then, import the module, then:

from polr import api

polr = api(apikey = "yourkeyhere")
polr.shorten("http://google.com")
>> u'http://polr.cf/1'

Node.js

You may perform a GET request to Polr's servers in order to shorten a URL, or use our Node.js wrapper (by fwilson).

Install the wrapper npm install polr, then docs needed. https://www.npmjs.org/package/polr

Shell

You may perform API calls through your shell by installing polr-cli. https://github.com/Cydrobolt/polr-CLI