Po.st REST API

Follow

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=txtoptional, 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_txtstatus_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)   
  1. country - is a country code for the geographical region pertaining to your specified link. Please use a correct code found from this list.
  2. states - is an array of state codes. Currently only supported for the US. Please use the correct codes found from the list
  3. platform - is a platform pertaining to your specified link. Could be iOS or Android.
  4. url - geographical or platform-specific link.
  5. fallbackURL - *optional - fallback URL for platform-specific link.
  6. 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 validationruleserrors
url
  1. must not be empty
  2. 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 ("-").")
  3. if scheme is not provided it is considered as http
  4. 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
  1. 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 ("-").")
  2. If scheme is not provided it is considered as http
  3. 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_txtstatus_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_txtstatus_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_txtstatus_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.
  • daysoptional, 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_txtstatus_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.

Was this article helpful?
0 out of 2 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk