BuzzData API

The BuzzData API allows you to access functionality and data programatically via oAuth2 secured API calls.

NOTE: This documentation covers the new version of the API that will be released soon. If you want access to this please contact [email protected] to request access.

If you are looking for the documentation for the current public API on buzzdata.com, head to the FAQ.

Pre-requisites

• In order to use the API, you must be able to use an oAuth2 library in the language of your choice.
• All API calls should be made over SSL connections.
• Your application server must not send the header X-Frame-Origin: DENY, or X-Frame-Origin: SAMEORIGIN as this will prevent the Application from being loaded inside an iFrame by the Browser. You should use the X-Frame-Origin: ALLOW-FROM buzzdata.com header, which you can read more about here. Please contact [email protected] if you have any queries about this flag.

Entity Relationship Overview

                                                                 +-------------+
                                +-------------------+            |Topics       |
                                | Dataset           |----------->|-------------|
                                |-------------------| 1        n |             |
                                |                   |            |             |
      +------------------+      |                   |            +-------------+
      | Datafile         |n    1|                   |
      |------------------|<-----|                   |----------->+----------+
      |                  |      +-------------------+ 1        1 | License  |
      |                  |        |1             1|              |----------|
      |                  |        |               |              |          |
      |                  |        |               |              |          |
      |                  |        |               |              +----------+
      |                  |        |               |
      +------------------+        |n             n|
                                  v               v
                       +---------------+      +-----------+
                       | Visualization |      | Article   |
                       |---------------|      |-----------|
                       |               |      |           |
                       |               |      |           |
                       +---------------+      +-----------+

Getting Started

BuzzData's API is REST based and uses basic HTTP communication with JSON responses. The API is only available to registered client applications, but it's easy to create one. You can follow the getting started guide.

Rate Limits

The API currently limits the requests you can make against it hourly. We have provided two response headers with each request to the API with Rate Limiting Information. They are returned from every API call.

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4998

X-RateLimit-Limit is your current limit per hour. X-RateLimit-Remaining is how many requests you have left. If you need more requests than 5,000/hr, please contact us and we'll do our best to accommodate you.

Client Libraries

• Ruby
• Written one? Let us know at [[email protected]](mailto:[email protected]?subject=I wrote a client library for BuzzData.)

Endpoints

Users

• GET :username - Get the details of a User.
• GET :username/datasets/list - Get the datasets a user has.
• POST users - Create a new user.

Licenses

• GET licenses - Get a list of Licenses available.

Topics

• GET topics - Get a list of topics available.

Search

• GET search - Search the public buzzdata.com site.

Datasets

Datasets are the overall container for Datafiles, Articles, Visualizations etc.

• Overview
• POST :username/datasets - Create a Dataset object to allow the uploading and publishing of Datafiles.
• POST :username/:dataset_short_name/upload_request - Upload a new Datafile to a Dataset.
• GET data_files/:DATAFILE_UUID/history - To retrieve the version history and release notes of a dataset.
• GET :username/:dataset_short_name - Retrieve the information about a Dataset.
• GET :username/:dataset_short_name/list_datafiles - Retrieves a list of Datafiles associated with a Dataset.
• POST upload_url - Send a POST request to the URL returned by your upload_request
• POST :username/:dataset_short_name/:datafile_uuid/download_request - Create a download_request
• DELETE :username/:dataset_short_name - Delete a Dataset.

Datafiles

Datafiles are the actual files associated with a Dataset that contain data, or are a document of interest.

• POST :username/:dataset_short_name - Creates a Datafile within a Dataset.

Articles

Articles are the image tiles represented in BuzzData when you visit a Dataset's Articles tab.

• DELETE :username/:dataset_short_name/articles/:uuid - Delete the corresponding article with the given UUID.
• GET :username/:dataset_short_name/articles - Retrieve a list of the Articles associated with the dataset.
• GET :username/:dataset_short_name/articles/:uuid - Retrieve a given Article associated with the dataset.
• POST :username/:dataset_short_name/articles - Create an Article on a given Dataset.

Visualizations

Visualizations are the image tiles represented in BuzzData when you visit a Dataset's Visualizations tab.

• DELETE :username/:dataset_short_name/visualizations/:uuid - Delete the corresponding visualization with the given UUID.
• GET :username/:dataset_short_name/visualizations - Retrieve a list of the Visualizations associated with the dataset.
• GET :username/:dataset_short_name/visualizations/:uuid - Retrieve a specific Visualization associated with the dataset under the given UUID.
• POST :username/:dataset_short_name/visualizations - Create a Visualizaiton from a URL.
• POST :username/:dataset_short_name/visualizations - POST an image you wish to user as a visualization.

Row Level Dataset Access

The Row Level Dataset Access allows you to add or remove rows from datasets by creating stages.

• Overview
• DELETE :username/:dataset_short_name/:datafile_uuid/stage/:stage_id - Delete a row
• POST :username/:dataset_short_name/:datafile_uuid/stage - To create a stage on a data file
• POST :username/:dataset_short_name/:datafile_uuid/stage/:stage_id/commit - To commit a stage
• POST :username/:dataset_short_name/:datafile_uuid/stage/:stage_id/rollback - To rollback a stage you don't want to commit
• POST :username/:dataset_short_name/:datafile_uuid/stage/:stage_id/rows - Insert one or more rows via a Stage
• PUT :username/:dataset_short_name/:datafile_uuid/stage/:stage_id/rows/:row_number - Update rows based on row number.