StatsMix API Documentation

Introduction

The StatsMix API is built using RESTful principles. We're working to expose more of our functionality via the API and all future updates will be contained in this document.

Authentication

Authentication is currently by API key. This can be sent in the header or as a parameter. You can find your API key under 'My Account' after signing into StatsMix.

Time Information

All datetimes are stored in the database as UTC. For daily email reports and charting on the StatsMix site, we convert from UTC to the user's timezone (can be changed in the settings section of the site).

The daily email process is set to kick off at 4am MST.

Response Codes

The following are the response codes we return with their descriptions:

200 Success
Everything went fine.

401 Authorized
Missing or incorrect API Key header.

403 Forbidden
You tried to access something you did not have permissions for.

404 Not Found

500 Internal Server Error

Getting Started

It's easy to get started with the StatsMix API. We currently only expose the stats resource, so there are still a few steps you'll need to complete on the website before using the API.

1) Create a new profile (if one doesn't already exist)

2) Add a new custom metric to the profile

3) The data you'll need to make an API call for that custom metric is now listed under "API details"

Available Resources

These are the currently available resources in the StatsMix API:

Stats

URL
http://www.statsmix.com/api/v1/stats

Parameters

Response

<?xml version="1.0" encoding="UTF-8"?>
<stat>
  <created-at type="datetime">2010-03-03T21:13:20-07:00</created-at>
  <generated-at type="datetime">2010-03-04T00:00:00-07:00</generated-at>
  <id type="integer">6271</id>
  <metric-id type="integer">12</metric-id>
  <profile-id type="integer">18</profile-id>
  <service-id type="integer" nil="true"></service-id>
  <service-type-id type="integer" nil="true"></service-type-id>
  <stat-type-id type="integer" nil="true"></stat-type-id>
  <updated-at type="datetime">2010-03-03T21:13:20-07:00</updated-at>
  <value type="integer">1</value>
</stat>

Libraries and Examples

In the following examples, user variables are indicated by uppercase (ex. API_KEY). Date values should be specific in the following format: YYYY-MM-DD (ex. 2010-02-22)

Curl Command Line

Curl is the easiest way to get started with the StatsMix API. Full documentation on how to use curl can be found here: http://curl.haxx.se/docs/manpage.html

Create a stat (POST)

curl -H "X-StatsMix-Token: API_KEY" -d "value=VALUE&profile_id=2&metric_id=1&generated_at=2010-02-22" statsmix.com/api/v1/stats

or

curl -d "value=VALUE&profile_id=PROFILE_ID&metric_id=METRIC_ID&generated_at=2010-02-22&api_key=API_KEY" statsmix.com/api/v1/stats

Show a stat (GET)

curl -H "X-StatsMix-Token: API_KEY" -G statsmix.com/api/v1/stats/STAT_ID.xml

Update a stat (POST)

curl -H "X-StatsMix-Token: API_KEY" -d "value=VALUE&profile_id=PROFILE_ID&metric_id=METRIC_ID" -X PUT statsmix.com/api/v1/stats/STAT_ID

Delete a stat (DELETE)

curl -H "X-StatsMix-Token: API_KEY" -X DELETE statsmix.com/api/v1/stats/STAT_ID

Ruby

In this example, a stat is posted using Ruby's net/http library.

require 'rubygems'
require 'net/http'
require 'uri'

url = URI.parse("http://www.statsmix.com/api/v1/stats")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url.path)
request.add_field("X-StatsMix-Token", "API_KEY")
request.set_form_data({
  "value" => "VALUE", 
  "profile_id" => "PROFILE_ID", 
  "metric_id" => "METRIC_ID", 
  "generated_at" => "DATE"
  })
response = http.request(request)
puts response.body

Pixel Tracking

The pixel tracking implementation of the StatsMix API is designed differently than the other examples. We offer a simplified call to the API specifically for sending us a new data point immediately when the pixel is downloaded. The typical usage for the pixel tracker would be to place the following line of code on a specific webpage. When the page is loaded, a data point is added to the specified metric.

<img src="http://www.statsmix.com/stats/iapi?v=VALUE&p=PROFILE_ID&m=METRIC_ID" width="1" height="1">