Swivel Business's API is REST like all the other vogue API kids, so it's easy as pie to push your numbers into Swivel and keep them freshly updated. Here's a quick one-two that'll help get your numbers in and updating automatically. All without installing libraries or writing code.
Numbers go here
First thing's first. You need data. But, how apropos, Swivel lets you access public data sets. Here's Apple's stock data. Get your data set into Swivel. It's easy. POST to /data_sets.xml. So you dig up your trusty tool, curl, and push the first 10 rows of this stock data up to Swivel:
curl -s -L http://api.swivel.com/v1/data_sets/1000800.csv | head -n 10 |
curl -X POST -F "api_key=API_KEY" \
-F "data_set[group_id]=WORKSPACE_ID" \
-F "data_set[name]=My Data" \
-F "file[types]=date,float,float,float,float,integer,float" \
-F "file[data]=<-" \
-k https://api.swivel.com/v1/data_sets.xml
and Swivel faithfully replies (modified for brevity):
<xml version="1.0" encoding="UTF-8"?>
<response at="Tue, 15 Jul 2008 16:53:43 -0700" total="" success="true" version="0">
<data-set>
<id type="integer">DATA_SET_ID</id>
<name>My Data</name>
<rows type="integer">3083</rows>
<last-data-update type="datetime">2008-07-15T17:02:32-07:00</last-data-update>
</data-set>
</response>
Swivel took your data and the parameters you set in curl and turned them into a data set. Sweet success. (It suits you.) But there're some gaps in the story, yet. Of note:
- curl -X POST tells curl to issue a POST http request. Since Swivel's API is REST, a POST tells Swivel to create something. In this case, we're creating a data set.
- api_key tells Swivel who you are. Any REST call that accesses a private data set requires an API key. Get your API key from our quick start guide. (Make sure you sign in.)
- data_set[group_id] tells Swivel which workspace the data set lives in. It's a weird parameter name. Just pretend group_id is really workspace_id, yeah? ;) You can get a list of your workspaces from our quick start guide.
- data_set[name] names your data set. For example, "THE MOST AMAZING DATA IN THE WORLD" or "website analytics".
- file[types] tells Swivel about the structure of your data set. It's a comma-separated list of data column types. Check the documentation to see all the data column types that Swivel understands.
- file[data] is the actual data as a CSV string.
- Optionally, set "data_set[public]=1" to make your data available to the world, and findable through Swivel's public data search.
- https://api.swivel.com/v1 is the REST endpoint. Swivel's API is versioned, so scripts that use the API will continue to work as we release updates.
- Swivel's XML response shows attributes of the data set, including the unique id identifier. You can easily get the data set's numbers:
curl -k https://api.swivel.com/v1/data_sets/DATA_SET_ID.csv?api_key=API_KEY.
"Yes We Can" keep data updated
Your data set is in Swivel. Now, you just need to keep your data up to date. It's REST, so you want to issue a PUT. This example uses the last 10 rows of Apple's stock data.
curl -s -L http://api.swivel.com/v1/data_sets/1000800.csv | tail -n 10 |
curl -X PUT -F "api_key=API_KEY" \
-F "file[data]=<-" \
-k https://api.swivel.com/v1/data_sets/DATA_SET_ID.xml
and Swivel says:
<?xml version="1.0" encoding="UTF-8"?>
<response at="Tue, 15 Jul 2008 17:12:56 -0700" total="" success="true" version="0">
<data-set>
<id type="integer">DATA_SET_ID</id>
<name>My Data</name>
<rows type="integer">19</rows>
<last-data-update type="datetime">2008-07-15T17:21:48-07:00</last-data-update>
</data-set>
</response>
The XML response is Swivel's way of telling you good stuff happened! (If bad stuff happened, Swivel tries to give you a decent error response with an appropriate http status code.) A more couple quick things:
- curl -X PUT tells curl to issue a PUT http request. In REST, a PUT means to update something. In this case, you're updating a particular data set.
- file[data] is the actual data as a CSV string. Swivel will append these new rows of numbers to your data set's existing numbers. You can also replace all the data set's numbers by using the file[mode] parameter. See the documentation.
- Swivel updated <rows>3085</rows> in the XML response. It grew by 10. Cool. You can double-check with
curl -s -k https://api.swivel.com/v1/data_sets/DATA_SET_ID.csv?api_key=API_KEY | wc
Now, do it automatically
After you have your update command figured out, you'll want to run it as a cron job. Here's an example:
$ crontab -l
# update my data set every night, at midnight
0 0 * * * ./get_new_data | curl -X PUT -F "api_key=API_KEY" -F "file[data]=<-" -k https://api.swivel.com/v1/data_sets/DATA_SET_ID.xml
Okay, pause for a sec. So, you can get your numbers into Swivel and keep them up-to-date. With two curl commands. And if you set data_set[public]=1, that up-to-date data is available to the world for free. This could be a moment. (Savor it.)
What's next?
Well, now that your numbers are in, what now? Swivel (the website) lets you monitor numbers and share insights.
There's more to Swivel's API too. Take a look at the real docs, starting at the developer's page. And there's a Swivel Developer Google Group where you can ask questions about Swivel's API or just say howdy to the Swivel team.
|
| Subscribe to swivel-developers |
| Visit this group |
Recent Comments