Step 5: An Introduction To awe.sm APIs

Last Updated: Oct 18, 2018 04:55PM PDT

Our platform really shines when you put the data to work powering features of your application. Easily use our flexible APIs to track user sharing, retrieve performance data, manage your account, and more. Learn about the different APIs we offer, and explore the various ways that you can use them.

Our APIs

awe.some offers 4 different APIs. Your account type dictates what APIs you are able to use. Please see the section API Access Restrictions (below) for more details on which accounts types can use each API.

Create API

The Create API enables the creation of trackable links which can be used for sharing content. Our share buttons for Facebook and Twitter leverage this API, and if you want to integrate with other social networks, or create custom sharing flows, this is the API you will use.

Conversions API

This API enables you to trigger conversions programmatically. This API is often used to enable conversion to be triggered “server-side” using web programming languages like PHP and Ruby, or “client side” using JavaScript.

Stats API

The Stats API gives you access to all of the data you have collected. This powerful API enables you to request any dataset, in virtually any combination. This API is most often used for integrating user sharing data into other applications.

Admin API

The Admin API enables you to manage your account settings programmatically. You can create, edit, and delete projects, users, and even custom domains.

API Access Restrictions

Each API is governed by access restrictions based on your account type. Please refer to the table below to determine which APIs you can use.

Create Conversions Stats Admin
Basic Reporting Plan Yes Yes No No
App Developer Plan Yes Yes Yes No
Premium Plan Yes Yes Yes Yes

Making API Calls

Our APIs can be invoked using standard HTTP GET requests. Because of this, you are able to call our APIs using virtually any language like, JavaScript, PHP, Ruby, Perl, Java, and more.

Simply select the API endpoint you want to call, provide any required parameters (like API version, and your API key), as well as any optional parameters available for that endpoint (like sort order, grouping, filters, etc). Below is an example of a call to our Stats API

<!– Get sharing activity totals from September 2012. –>
http://api.awe.some/stats/range.json?v=3&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&start_date=2012-09-01&end_date=2012-10-01

A complete list of API endpoints and their parameters is available in our API Documentation.

API Responses

Every request to an awe.some API endpoint will generate both a HTTP status and an output. The HTTP statuses are standard statuses like like 200, 201, and 400. These can be used to understand if your request was received and processed by the server.

The output contain the actual data sent back for your request. By default the server will return a JSON formatted response. But, If you prefer, on many API endpoints you can specify a plain-text response instead. Below is an example of the response from the above mentioned Stats API call:

<!– The Results From The Sample API Call Above –>

{
“end_date”: “2011-10-01T00:00:00Z”,
“filters”: [],
“group_by”: null,
“groups”: [],
“last_offset”: 0,
“offset”: 0,
“page”: null,
“per_page”: 10,
“pivot”: null,
“pivot_sort_order”: null,
“pivot_sort_type”: null,
“sort_order”: null,
“sort_type”: null,
“start_date”: “2011-09-01T00:00:00Z”,
“total_results”: 0,
“totals”: {
“clicks”: 166,
“clicks_per_share”: 2.5538,
“shares”: 65
},
“with_conversions”: false,
“with_metadata”: false,
“with_zeros”: false
}

Next Steps – Go Build Something Awesome!

If you are ready to start using our APIs, you can find specific instructions on how to use each API in our API Documentation. There you will find a listing of the specific parameters available to each call, as well as additional examples which can help you get started.