awe.sm Create API: Static Endpoint

Static Endpoint

This endpoint is meant to be used by an application that needs a working redirect link to display in the interface but doesn't want to create a new link for every page load (e.g. to display as a 'short permalink' for a given page).

If an awesm_url with the specified metadata already exists, it will be returned in the response. If an awesm_url with the specified metadata does not already exist, a new one will be created and returned in the response.

Please note that the primary value of awe.sm comes from using a unique link per share action wherever possible. Re-use of a given awesm_url should be avoided in all use-cases for which it isn't required.

If, for example, an awesm_url is needed to display in a message composition field before it is to be shared, it can either be substituted out with a dynamically created link at the time of the share using the Retweet Endpoint or have its share metadata updated after it is shared via the Update Endpoint. In the latter case, you would want to use the Create Endpoint for generating the initial display awesm_url, in order to ensure it is unique).

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

POSTapi.awe.sm/url/static.{format}

The GET method is also supported. HTTPS is supported on this endpoint.

Required Parameters

Parameter	Type	Description
format	string	Data format of response: `json` or `txt`. This parameter is provided as part of the URL. Passing it as an explicit parameter will have no effect. A 400 error will be returned if an invalid format is specified.
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.
url	string	The address of the page being shared, subject to redirection patterns.
v	integer	API version: `3` for this endpoint.

Optional Parameters

Parameter	Type	Description
channel	string	Where the created awe.sm link will be shared. See Services and Channels for list of common values.
callback	string	Returns a JSON-P response named with this parameter's value. Requires `json` as the requested `format`.

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	A project-specific label for filtering and high cardinality grouping with no additional attributes. Case-sensitive.
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

Create a link tied to a specific Plancast user to be displayed for them to copy from the an event page via GET with full JSON response (using a demo API Key and test Tool Key)

GET http://api.awe.sm/url/static.json?v=3&url=http://plancast.com/p/6xfs/silicon-valley-tweetup-summer-2011&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&tool=mKU7uN&channel=copypaste&user_id=23291&user_id_username=jhstrauss&user_id_profile_url=http://plancast.com/user/23291&user_id_icon_url=https://fbcdn-profile-a.akamaihd.net/hprofile-ak-snc4/41657_627286_9900_n.jpg

{
    "awesm_url": "http://demo.awe.sm/ELZ",
    "awesm_id": "demo.awe.sm_ELZ",
    "domain": "demo.awe.sm",
    "path": "ELZ",
    "created_at": "2011-08-19T23:39:15Z",
    "redirect_url": "http://plancast.com/p/6xfs/silicon-valley-tweetup-summer-2011?utm_campaign=&utm_medium=demo.awe.sm-copypaste&utm_source=direct-demo.awe.sm&utm_content=test-main",
    "original_url": "http://plancast.com/p/6xfs/silicon-valley-tweetup-summer-2011",
    "channel": "copypaste",
    "service": "copypaste",
    "tool": "test-main",
    "application": "test",
    "parent": null,
    "sharer_id": null,
    "username":null,
    "service_userid": null,
    "service_postid": null,
    "service_postid_metadata": {
        "reach": null,
        "shared_at": null
    },
    "campaign": null,
    "campaign_metadata": {
        "description": null,
        "name": null
    },
    "user_id": "23291",
    "user_id_metadata": {
        "icon_url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-snc4/41657_627286_9900_n.jpg",
        "username": "jhstrauss",
        "profile_url": "http://plancast.com/user/23291"
    },
    "tag": null,
    "notes": null,
    "new": false
}

Last updated 2012-01-23