Sign up now 30 days free. Cancel anytime.

Have questions? Talk to us.

877-OK-AWESM  877-OK-AWESM Live chat Live chat developers@awe.sm developers@awe.sm Schedule a webinar Schedule a webinar

awe.sm Create API

Share Endpoint

Creates a new awesm_url with specified metadata and shares it to the specified un-authenticated sharing API (e.g., Twitter Web Intents, Facebook Feed Dialog, etc.). These calls are meant to be used directly in end-user facing UIs and attached directly to sharing calls-to-action like a "Tweet This" link (this endpoint is what powers our own Share Buttons).

Known bots (like web crawlers) are blacklisted from creating links via this endpoint. You may run into this if you attempt to curl this endpoint directly, if you do not send a valid user-agent header.

Create API requests are limited to 8,000 per hour.

GETapi.awe.sm/url/share

HTTPS is supported on this endpoint.

Required Parameters

Parameter Type Description
channel string Where the created awe.sm link will be shared. See Services and Channels for list of common values.
destination string The URL to which the user should be redirected to upon clicking on this link. All instances of the string "AWESM_URL" will be replaced by the specified url parameter. This value must be URL encoded, including switching any &'s or #'s to %26 and %23, respectively. If the destination is Twitter, make sure to double encode any &s or #s in the text argument, e.g., . The redirect uses status code 302.
key string API key of the project with which the created awe.sm link should be associated.
tool string A unique key representing the creation method of the awe.sm link. See the Link Creation Overview for more information.
v integer API version: 3 for this endpoint.

Optional Parameters

Parameter Type Description
errors boolean Default FALSE. Determines whether or not the API responds with an error code when awe.sm link creation fails and a destination value is specified. If FALSE and an error occurs, the user will be redirected to the destination value using the specified url value for AWESM_URL.
url string The address of the page being shared, subject to redirection patterns. By default, the http_referer will be used for the URL parameter. An error will be thrown if the http_referer is invalid.

Metadata Parameters

Parameter Type Description
campaign string A project-specific label for filtering and low cardinality grouping. This is the stubified identifier of a campaign_name (i.e., a-z0-9_-). If a campaign value that isn't stubified (e.g., a human-readable name) is specified, we will automatically stubify it for the campaign value and save the submitted value as the campaign_name.
campaign_description string A human-readable description of a campaign. Requires a valid campaign. Must be specified when a campaign is created. Returned when with_metadata=true in Stats API requests.
campaign_name string A human-readable name of a campaign. Requires a valid campaign. Must be specified when a campaign is created. If no campaign_name is explicitly specified, the non-stubified campaign value will be used. Returned when with_metadata=true in Stats API requests.
notes string An arbitrary, open-ended field retrievable only on individual awe.sm links. Maximum length of 256 characters.
parent string

The awesm_id that drove the visit that led to this awe.sm link being created. See Link Creation overview for more information.

If the url itself is an awe.sm link or contains an awesm URL parameter that belongs to the project, it automatically will be set as the parent value, unless otherwise specified.
service_userid string

The user id of the sharer on the service being shared to. Value must be formatted service:user_id, where "service" corresponds to the service of the specified channel. Example: twitter:13263 for tweets made by @jhstrauss.

A 400 error will be returned if the service is incorrectly specified. If only a numerical user id is specified (i.e., no leading string and colon) and a known channel with a corresponding service value is specified, the service value and colon will be automatically pre-pended. Do not rely on this behavior.
tag string or array of strings A case-sensitive field capable of storing multiple values up to 255 characters. Use a URL array in multiple value mode (tag_3[]=foo&tag_3[]=bar) or a key-value pair (tag_3=foo) in single value mode. See the Tag Overview for more information.
tag_2
tag_3
tag_4
tag_5
user_id string Your application's unique identifier for the user initiating the share. Case-sensitive, so we suggest using numeric identifiers.
user_id_icon_url string URL of the profile image of the user initiating the share. Requires a valid user_id. Must be specified when the user is first identified with awe.sm. Returned when with_metadata=true in Stats API requests.
user_id_profile_url string URL of the user's profile in your application. Requires a valid user_id. Must be specified when the user is first identified with awe.sm. Returned when with_metadata=true in Stats API requests.
user_id_username string Human-readable username associated with the user initiating the share. Requires a valid user_id. Must be specified when the user is first identified with awe.sm. Returned when with_metadata=true in Stats API requests.

Advanced Parameters

Parameter Type Description
domain string The custom domain on which the awe.sm link will be created. Defaults to the custom domain default set in Project Settings. A 403 error will be returned if the project does not have access to the domain specified.
path string The extension you want on the awesm_url to be created. We recommend using this field only when you don't care about tracking, since static links that are used multiple times don't provide the same level of tracking as dynamically-generated links that are unique per share action. Our 404 pass-through feature might make more sense. Cannot be used in the Retweet Endpoint. If multiple values are specified for any other parameters in the Create Batch Endpoint and a single path is specified, an error 400 will be returned.

Examples

Share this page on Twitter in a new window (using a demo API Key and test Tool Key)

<a href="http://api.awe.sm/url/share?v=3
&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9
&tool=mKU7uN&channel=twitter
&destination=http://twitter.com/intent/tweet?text=This+is+the+coolest+API+evar!%26url=AWESM_URL%26via=awesm" 
target="_blank">Tweet This</a>

Try it: Tweet This

Share this page on Facebook in a new window (using a demo API Key and test Tool Key)

<a href="http://api.awe.sm/url/share?v=3
&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9
&tool=mKU7uN
&channel=facebook-share
&destination=http://facebook.com/sharer.php?u=AWESM_URL" target="_blank">
Share This on Facebook</a>

Try it: Share This on Facebook

Share this photo (of Team awe.sm!) on Tumblr (using a demo API Key and test Tool Key, based on official Tumblr button embed code)

<!-- Put this tag wherever you want your button to appear -->
<span id="tumblr_button_abc123"></span>

<!-- Set these variables wherever convenient -->
<script type="text/javascript">
    var tumblr_photo_source = "http://farm6.static.flickr.com/5016/5513615454_79de54363d_s.jpg";
    var tumblr_photo_caption = "These guys rule!";
    var tumblr_photo_click_thru = "AWESM_URL";
    var awesm_original_url = "http://www.flickr.com/photos/31454690@N00/5513615454/in/pool-1107348@N23/";
    var awesm_channel = "tumblr-photo";
    var awesm_tool = "mKU7uN";
    var awesm_api_key = "5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9";
</script>


<!-- Put this code at the bottom of your page -->
<script type="text/javascript">
    var tumblr_button = document.createElement("a");
    tumblr_button.setAttribute("href", "http://api.awe.sm/url/share?v=3&url=" + encodeURIComponent(awesm_original_url) + "&key=" + encodeURIComponent(awesm_api_key) + "&tool=" + encodeURIComponent(awesm_tool) + "&channel=" + encodeURIComponent(awesm_channel) + "&destination=http://www.tumblr.com/share/photo?source=" + encodeURIComponent(encodeURIComponent(tumblr_photo_source)) + "%26caption=" + encodeURIComponent(tumblr_photo_caption) + "%26clickthru=" + encodeURIComponent(tumblr_photo_click_thru));
    tumblr_button.setAttribute("title", "Share on Tumblr");
    tumblr_button.setAttribute("style", "display:inline-block; text-indent:-9999px; overflow:hidden; width:81px; height:20px; background:url('http://platform.tumblr.com/v1/share_1.png') top left no-repeat transparent;");
    tumblr_button.innerHTML = "Share on Tumblr";
    document.getElementById("tumblr_button_abc123").appendChild(tumblr_button);
</script>

Try it: Share on Tumblr

Last updated 2013-06-18