Po.st REST API – Po.st Support Center

Shorten

For a long URL, encodes a URL and returns a short one.

Resource URL

http://po.st/api/shorten

Parameters

apiKey – your API access token. Sign up for a free key here.
longUrl – is a long URL to be shortened (example: http://radiumone.com).
format=txt – optional, enables a simplified response – just the shortened link in text format.

Notes

Long URLs should be URL-encoded. You cannot include a longUrl in the request that has '&', '?', '#', ' ' or other reserved parameters without first encoding it.
Long URLs should not contain spaces: any longUrl with spaces will be rejected. All spaces should be either percent encoded (%20) or plus encoded (+). Note that tabs, newlines and trailing spaces are all indications of errors. Please remember to strip leading and trailing whitespace from any user input before shortening.

Response

status_txt– status code, see below
- OK
- INVALID_URL – check requirements for longUrl above
- RATE_LIMIT – rate limit exceeded
- AUTH_ERROR – invalid apiKey
- INTERNAL_ERROR
long_url – is an echo back of the longUrl request parameter. This may not always be equal to the URL requested. That's because some URL normalization may occur (e.g., due to encoding differences, or case differences in the domain). This long_url will always be functionally identical the request parameter.
hash – is a Po.st identifier for long_url which is unique to the given account.
short_url – is the actual short URL to be used.
new_hash – designates if this is the first time this long_url was shortened by this API user. The return value will equal 1 the first time a long_url is shortened.

Examples

GET
{
           "status_txt":"OK",
           "long_url":"http://radiumone.com/",
           "hash": "mBXhkf",
           "short_url":"http://po.st/mBXhkf",
           "new_hash":1
}

GET

Response: http://po.st/mBXhkf

GET
http://po.st/api/shorten?longUrl=test&apiKey=YourApiKey
{
"status_txt":"INVALID_URL",
}

Errors

status_txt	status_code
OK	0
AUTH_ERROR	41
RATE_LIMIT	43
INTERNAL_ERROR	51
INVALID_URL	411
CAMPAIGN_ARCHIVED	42

Customize

For a shortened URL, looks up provided hash and swaps it with desired custom hash and/or changes it's long URL.

Resource URL

http://po.st/api/customize

Parameters

apiKey – your API access token. Sign up for a free key here.
hash – existing hash of short (example: 2HdX3b ).
customHash – *optional - desired hash (example: customHash)
longUrl - *optional - new long URL *To enable your account to edit Long URLs please contact your Po.st Account Manager.
Smart Links - *Optional - add geographical and platform-specific URLs to your links. The value is JSON formatted (also should be urlencoded)

country - is a country code for the geographical region pertaining to your specified link. Please use a correct code found from this list.
states - is an array of state codes. Currently only supported for the US. Please use the correct codes found from the list.
platform - is a platform pertaining to your specified link. Could be iOS or Android.
url - geographical or platform-specific link.
fallbackURL - *optional - fallback URL for platform-specific link.
fallbackIsAppInstallUrl - *optional - Does fallback URL point to App Store?

            [
              {
               "country": ,
               "states": ,
               "platform": <true/false>,
               "url" : <IOS/AND>,
               "fallbackUrl": ,
               "fallbackIsAppInstallUrl": 
              },
              {...}
             ]

smartLinksReset - *optional - removes all current smartLinks. Could be true/false (false by default)

Response

status_txt– status code, see below
- OK
- INVALID_URL – invalid longUrl, check requirements above
- RATE_LIMIT – rate limit exceeded
- AUTH_ERROR – invalid apiKey value
- INVALID_GEO_CODE - the <CountryCode> is invalid
- INVALID_GEO_URL - invalid geoLinks.<CountryCode> value
- INTERNAL_ERROR
short_url - resulting short link

Errors

INVALID_HASH (421) and INVALID_CUSTOM_HASH (422) - hash and/or customHash not been validated (blank or contain characters other than numbers and Latin letters)
ALREADY_EXIST (423) - Custom hash is already registered and taken;
ORIGINAL_HASH_NOT_FOUND (424) - The hash provided was not found in the system (make sure your short URL already exists).
EDIT_LONG_URL_FORBIDDEN (427) - request contains longUrl parameter but account associated with apiKey isn't allowed to edit long URL.
INVALID_GEO_CODE (428) - The <CountryCode> is invalid, please use a correct code found from this list.
INVALID_GEO_URL (425) - The URL value for one or more geoLinks.<CountryCode> is invalid, use only encoded URLs
INVALID_SMART_LINKS(434) - smartLinks parameter is invalid

New field errors with details added:

        {
         "status_code": "434",
         "status_txt": "INVALID_SMART_LINKS",
         "errors": [
          {
           "code": "",
           "smartLink": {"country": "", "platform": "", "states":
        <states>},
           "field": "",
           "message": ""
          },
          ...
         ]
        }

part of smartLinks for validation	rules	errors
url	must not be empty can be https://, http://, custom app scheme(for a example fb://), without scheme, but if scheme presents it must be valid (A valid RFC 3986 URL scheme must consist of "a letter and followed by any combination of letters, digits, plus ("+"), period ("."), or hyphen ("-").") if scheme is not provided it is considered as http if scheme is http or https or ftp the same validation rules is used as for long_url while shortening	{ "code": "INVALID_URL", "smartLink": {"country": "<country_code>", "platform": "<platform_code>", "states": <states>}, "field": "url", "message": "Not a valid url" }
fallback	can be https://, http://, custom app scheme(for a example fb://), without scheme, but if scheme presents it must be valid (A valid RFC 3986 URL scheme must consist of "a letter and followed by any combination of letters, digits, plus ("+"), period ("."), or hyphen ("-").") If scheme is not provided it is considered as http If scheme is http or https or ftp the same validation rules is used as for long_url while shortening	{ "code": "INVALID_FALLBACK", "smartLink": {"country": "<country_code>", "platform": "<platform_code>", "states": <states>}, "field": "fallback", "message": "Not a valid fallback url" }
country	must be from this list	{ "code": "INVALID_PLATFORM_CODE", "smartLink": {"country": "<country_code>", "platform": "<platform_code>", "states": <states>}, "field": "country", "message": "Not a valid country code" }
platform	must be iOS or Android	{ "code": "INVALID_PLATFORM_CODE", "smartLink": {"country": "<country_code>", "platform": "<platform_code>", "states": <states>}, "field": "platform", "message": "Not a valid platform code" }
states	codes must be from the states list	{ "code": "INVALID_STATE_CODE", "smartLink": {"country": "<country_code>", "platform": "<platform_code>", "states": <states>}, "field": "states", "message": "Not a valid state code" }
country,platform	either country or platform should be provided	{ "code": "INVALID_STATE_CODE", "smartLink": {"country": "<country_code>", "platform": "<platform_code>", "states": <states>}, "field": "states", "message": "Not a valid state code" }
fallback, fallbackIsAppInstallUrl	The fallback is missing, but fallbackIsAppInstallUrl provided	{ "code": "INAPPROPRIATE_FALLBACK_DATA", "smartLink": {"country": "<country_code>", "platform": "<platform_code>", "states": <states>}, "message": "The 'fallback' missing, but 'fallbackIsAppInstallUrl' provided" }
	smartLinks contains not a valid JSON	{ "code": "SMART_LINKS_JSON_NOT_VALID", "message": "Parameter 'smartLinks' contains not a valid JSON" }
	Smart link with the same county/region/platform fields mentioned two or more times	{ "code": "SMART_LINK_MENTIONED_TWICE", "message": "Smart link with the same of fields 'country'/'region'/'platform' mentioned two or more times" }
	states currently supported only for the US	{ "code": "INVALID_COUNTRY_STATES_COMBINATION", "message": "Invalid country/states combination" }

Examples

Setting Custom Hash

Request

GET

Response


 {           
            "status_txt": "OK", 
            "status_code": 0
            "short_url": "http://po.st/customHash"
}

Setting Smart Link

Request

GET

where smartLinks is an encoded JSON:

[
  {
      "url": "app://mainpage",
      "platform" : "IOS",
      "country": "BY"
  }
]

Response

{
       "status_txt": "OK",
       "status_code": 0,
       "short_url": "http://po.st/2HdX3b"
}

Errors

status_txt	status_code
OK	0
AUTH_ERROR	41
RATE_LIMIT	43
INTERNAL_ERROR	51
CAMPAIGN_ARCHIVED	42
ALREADY_EXIST	423
INVALID_HASH	421
INVALID_CUSTOM_HASH	422
ORIGINAL_HASH_NOT_FOUND	424
EDIT_LONG_URL_FORBIDDEN	427
INVALID_SMART_LINKS	434

Expand

Given a Po.st URL or hash, decodes it and returns back the target URL.

Resource URL

http://po.st/api/expand

Parameters

apiKey – your API access token. Sign up for a free key here.
shortUrl – a Po.st URL to be expanded (e.g. http://po.st/mBXhkf)
hash – a Po.st hash of the URL to be expanded (e.g. mBXhkf)

Either shortUrl or hash should be provided.

Response

status_txt – status code, see below

◦ OK

◦ NOT_FOUND

◦ RATE_LIMIT – rate limit exceeded

◦ AUTH_ERROR – invalid apiKey

◦ INTERNAL_ERROR

long_url – is the URL that the requested shortUrl or hash points to.
hash – an echo back of the hash request parameter.
short_url – an echo back of the shortUrl request parameter.

Examples

GET

{
            "status_txt":"OK",
            "long_url":"http://radiumone.com/",
            "short_url":"http://po.st/mBXhkf"
}

GET
http://po.st/api/expand?hash=mBXhkf&apiKey=YourApiKey
{
            "status_txt":"OK",
            "long_url":"http://radiumone.com/",
            "hash": "mBXhkf"
}

Errors

status_txt	status_code
OK	0
AUTH_ERROR	41
RATE_LIMIT	43
INTERNAL_ERROR	51
NOT_FOUND	44

Daily statistics for particular URL/hash

Resource URL

http://po.st/api/daily

Parameters

apiKey – your API access token. Sign up for a free key here.
shortUrl – refers to URLs, (e.g.: http://po.st/12sdf2 or http://mydoma.in/234sd3).
hash – refers to hash, (e.g.:12sdf2).
days – (optional) an integer value for the number of days (counting backwards from the yesterday) from which to retrieve data (min:1, max:365, default:7).

Notes

Either shortUrl or hash must be given as a parameter.

Response

short_url – this matches the shortUrl request parameter.
hash – this matches the hash request parameter.
long_url – is the corresponding long URL.
total_clicks_your – is the total number of clicks to this link in the specified time period
total_clicks_all – this is the total count of clicks to all links that point to the same long url in the specified time period
days – is an echo of the "days" parameter
day_start – is time (in mills) code representing the start of the day (in EST TimeZone) for which click data is provided.
clicks_your – this is the total count of clicks to this link.
clicks_all – this is the total count of clicks to all links that point to the same long url.

Example

GET
http://po.st/api/daily?apiKey=YourApiKey&hash=12sdf2
{
           "status_txt": "OK",
           "short_url": "http://po.st/12sds3",
           "hash": "12sds3",
           "long_url": "http://radiumone.com",
           "total_clicks_your": 11,
           "total_clicks_all": 12,
           "days": 3,
           "clicks": [
{
           "clicks_your": 4,
           "clicks_all": 4,
           "day_start": 1291093200000
}, {
           "clicks_your": 6,
           "clicks_all": 7,
           "day_start": 1291006800000
}, {
           "clicks_your": 1,
           "clicks_all": 1,
           "day_start": 1290920400000
  }
]
}

Errors

status_txt	status_code
OK	0
AUTH_ERROR	41
RATE_LIMIT	43
INTERNAL_ERROR	51
NOT_FOUND	44

Daily statistics for all URLs generated with particular apiKey

Resource URL

http://po.st/api/partner/daily

Parameters

apiKey – your API access token. Sign up for a free key here.
days – optional, an integer value for the number of days (counting backwards from the yesterday) from which to retrieve data (min:1, max:365, default:7).

Notes,

Results are returned in reverse chronological order (from most recent to least recent).

Response

days – an echo of the "days" parameter.
total_clicks – the total number of clicks in the specified time period.
clicks – the total number of clicks on that day.
day_start – is time (in mills) code representing the start of the day (in EST TimeZone) for which click data is provided.

Example

GET
http://po.st/api/partner/daily?apiKey=YourApiKey
{
           "status_txt": "OK"
           "days": 3,
           "total_clicks": 11,
           "clicks": [
{
           "clicks": 4,
           "day_start": 1291093200000
}, {
           "clicks": 6,
           "day_start": 1291006800000
}, {
           "clicks": 1,
           "day_start": 1290920400000
  }
]
}

Errors

status_txt	status_code
OK	0
AUTH_ERROR	41
RATE_LIMIT	43
INTERNAL_ERROR	51
NOT_FOUND	44

Rate Limiting

Rate limiting is the limit to the number of API requests that can be made during a particular span of time. These limits are applied at the campaign level in the format <number of requests>/<time period> - <time before another request can be made>.

For example 10/1s-2m would translate to

10 requests made in 1 second. You will need to wait 2 minutes before another request can be processed.

Po.st REST API	Resource URL	Rate Limiting
Shorten	http://po.st/api/shorten	10/1s-10s, 1000/1h-1h
Customize, Expand	http://po.st/api/customize http://po.st/api/expand	10/1s-10s
Daily statistics for particular URL/hash, Daily statistics for all URLs with same apiKey	http://po.st/api/daily http://po.st/api/partner/daily	300/1h-1h

See attached word document for a downloadable version of our API.

Shorten

Resource URL

Parameters

Notes

Response

Examples

Errors

Customize

Resource URL

Parameters

Errors

Examples

Setting Custom Hash

Request

Response

Setting Smart Link

Request

Response

Errors

Expand

Resource URL

Parameters

Response

Examples

Errors

Daily statistics for particular URL/hash

Resource URL

Parameters

Notes

Response

Example

Errors

Daily statistics for all URLs generated with particular apiKey

Resource URL

Parameters

Notes,

Response

Example

Errors

Comments