Shorten
For a long URL, encodes a URL and returns a short one.
Resource URL
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
{
"status_txt":"OK",
"long_url":"http://radiumone.com/",
"hash": "mBXhkf",
"short_url":"http://po.st/mBXhkf",
"new_hash":1
}
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
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 |
|
{ "code": "INVALID_URL", "smartLink": {"country": "<country_code>", "platform": "<platform_code>", "states": <states>}, "field": "url", "message": "Not a valid url" } |
fallback |
|
{ "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
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
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
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
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
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.
Comments