Skip to content

Home

Jump to bottom
Daniel James edited this page Mar 9, 2016 · 19 revisions

#Introduction

The ScoreBig API is a simple REST web service interface with lightweight JSON-formatted responses, providing you the capability to use many of the functions and data of ScoreBig's platform. This document provides comprehensive information for developers to easily and quickly create applications based on ScoreBig's functionality. Anyone can use the API free of charge by simply signing up for access, and it's easy. Read on to find out more...

#Available APIs

API Feeds (read-only)

Broker APIs (transactional)

#APIs In Development

#Before You Begin

Sound great so far? Here's what you need to start using the ScoreBig API:

  • Read our documentation - you'll find everything you need here to get up and running in no time.
  • Email us at developer@scorebig.com to get your hands on your API access key. Yeah, we hate filling out forms too!.
  • Start writing some code and don't forget to send us a note when it's done so we can check it out!

#The Basic Stuff You Need to Know

The ScoreBig API is implemented as a stateless RESTful web service. For a quick primer on what REST web services are, start here: http://en.wikipedia.org/wiki/REST

All responses returned by the API calls are in JSON, which is a standards-based lightweight serialization format for data interchange. If you haven't used JSON before, check it out here: http://en.wikipedia.org/wiki/Json

We may support other data formats such as XML in the future, so check back here for API updates.

#Version

The current API Version is 1. The Version number will always be incremented in whole integers. You can access specific versions of the API by providing that version number in your API calls, which are detailed further below.

#Entry Point

###Production The current version of the ScoreBig API is available at: http://api.scorebig.com/1.

HINT: if you are an affiliate, be sure that you connect directly to our production API.

###Developer sandbox The developer sandbox for the ScoreBig API is available at: http://apisandbox.scorebig.com/1

#Authentication

The ScoreBig API requires an API key to access which is provided when you sign up for API access. The API key identifies your application to ScoreBig, and is used to track overall call usage. It's passed using the api_key parameter that you will need to supply on every API call.

#Rate limiting

Clients are allowed 10,000 requests per 24-hour period, with a limit of 10 queries per second. If you exceeded the maximum allowed number of calls, our system will return an HTTP 403 Forbidden response, along with a detailed error message indicating why the request was refused. See the section "API Responses" below for further details.

If your application needs more than the allotted amount of calls, contact us at developer@scorebig.com with a description of the application and an estimate on needed call usage. These default rate limits are subject to change at any time, without notice.

#API Requests

The ScoreBig API uses a RESTful calling style that works with standard HTTP calls. In other words, all calls are just HTTP URLs. Any web programming language (PHP, Ruby, Perl, Python, Java, Objective C, C# to name a few) should be able to make and receive HTTP networking calls, so check out the documentation for your language of choice for more details.

In a RESTful API, each resource or collection of resources is identified by a unique URL, such as:

http://api.developer.scorebig.com/1/events

It's a bit more complicated than that, however, since every request you make needs to have your API key supplied. Think of this as your user id and password. Since RESTful web services are generally stateless, you need to supply those credentials in every request.

In addition, you must specify which version of the API you'd like to call. As mentioned earlier, this is a simple integer value that gets incremented every time significant changes to the API are made (changes that would break compatibility with existing applications). If you can't keep up with ScoreBig's API changes and don't want to use the latest and greatest version, then you can always supply an earlier version specifier in your call. We'll do our best to keep the older versions of the API hanging around.

So the basic format for any URL to call the ScoreBig API is as follows:

http://api.developer.scorebig.com/{apiVersion}/{pathToResource}?api_key={:api_key}

A full example of an API call would be the following:

http://api.developer.scorebig.com/1/events?api_key=0FFA1519-22D6-454E-B2FA-9D9F017D522E

URLs for specific API calls are discussed in more detail in the sections that follow.

The default format for the service is JSON, in order to access the service, make sure the Content-Type (set in the request header) of the request is set to:

Content-Type: application/json; charset=utf-8

#HTTP Methods

RESTful APIs use standard HTTP methods for actions that can be applied to a resource:

Method Description Status Code
GET Reads a resource HTTP 200 on success
POST Creates a new resource HTTP 201 on success
PUT Inserts or Updates a resource HTTP 200 on success
DELETE Deletes a resource HTTP 200 on success

API Responses

All GET API calls will return a JSON response within a standard data structure that also contains additional meta-data:

{
     "count":integer,
     "results": [
         { result object }
     ],
     "type":result type
}

Where count is the number of results returned, results is the array of the returned objects, and type is the type of the object returned.

For the sake of consistency, the result field will always return an array, even if the number of results returned is 1.

For POST, PUT and DELETE API calls, a status JSON response message will be returned:

{
     "type": "Result",
     "results": [{ message: "Event deleted", data: [null] }],
     "count": 1
}

#Response Codes

As with all RESTful interfaces, the ScoreBig API uses standard HTTP status codes to indicate success or failure of API calls. Determining the HTTP status code of the returned response is dependent on your toolkit/programming language so consult its documentation for implementation details.

HTTP Code
Message
Meaning
200 OK Success
201 Created A new resource was successfully created.
400 Bad Request Your request contains an error, such as passing a string for a parameter that expects an integer.
401 Unauthorized Your request contained an incorrect api_key and/or other authentication parameters.
403 Forbidden The rate limits for your account have been exceeded, the data you're trying to access is private, or the method you're using is not allowed for that particular resource.
404 Not Found The requested resource could not be found or does not correspond to any known operation.
500 Server Error An unexpected error has occurred on our end.
503 Service Unavailable The ScoreBig API is down for scheduled maintenance; please try again later (this should hardly ever happen though!)

All responses return a JSON-formatted result body, even for errors. For status codes other than 200 and 201, an error object is returned in the response body, with exact details on the cause of the error. For example:

{
    "http_status_code":401,
    "errors": { message: [ "invalid_city_code", "invalid_date_range" ] }
}

What's the difference between a 404 Not Found and a 200 OK with empty results? If you're searching for a specific record, say event BA5965A4-EAF4-44CC-B3A8-011ED7220E73, and it doesn't exist, 404 Not Found is returned. The record wasn't found in our system because it no longer exists (or maybe never even existed). However, if you're searching for a set of events and no listings match your search, 200 OK is returned, but with an empty array in the results field. There's nothing wrong with your request, but there were no matching records found so an empty result is returned.

While this may seem a bit weird, it makes practical sense: if you use a search engine to find something and no matching results were found, it doesn't return an error page. But if you're trying to access a URL that doesn't exist, a standard 404 error page would be returned. It's likely that your application should behave similarly.

#Error Codes

If an error response is returned, the message field will contains an array of error codes. Each error code meant to be human-readable but can be treated as a constant and used in your application to respond to the error accordingly. We will explain each call-specific error code later but here are the system wide error codes:

Error Code
Meaning
invalid_api_key The API key used is invalid. Please email developer@scorebig.com for assistance.

Clone this wiki locally