Getting Started With The API

API Parameters

To access the API the first thing you need to retrieve your API parameters. This can be found under the top menu in the dashboard under API.

API Key

The API key is used to identify the user account for the request being made.

Secret Key

The secret key is used to hash data from the client and then verified on the server. The secret key should not be shared, publically visible or accessible.

API Wrappers

If you want to get up and running quickly then download one of our API wrappers. These contain functionality to quickly use our API.

Authentication

Each API request must contain a timestamp and authentication header. These ensure the request was sent by you and not a third party. To verify your signature you can use this online site to generate your base64 string with the secret key and compare it against your code generated signature.

Signed Request

The signed request is stored in the authentication header of the request and is composed of the API key and a base64 encoded hashed signature seperated by a period.

Authentication Header Format

{Api Key}.{Signature}

Authentication Header Example

999a99he0TR297.qEOgRhIYrXD/vPIL7AJh14lvCGGv4VVAS4ATjqCNtUo=

The message being hashed is composed of the following parameters in the following order: API key, http verb, timestamp, and the relative URI. These parameters are seperated by an ampersand (&), and should be upper case.

API Key

The first parameter is the API key mentioned above.

Http Verb

The second parameter is the http verb of the request. This includes GET, POST, PUT, and DELETE.

Timestamp

The third parameter is the timestamp and needs to be the current ISO 8601 format (2012-09-27T20:33:55.3564453Z).

Relative URI

The last parameter is the relative URI (/api/v1/events) of the request. This excludes the host (https://baseball.exposureevents.com) and query strings (?id=1).

Signature Format

{API KEY}&{HTTP VERB}&{TIMESTAMP}&{RELATIVE URI}

Signature Example

999A99HE0TR297&GET&2012-09-27T20:33:55.3564453Z&/API/V1/EVENTS

The signature is hashed using the HMAC-SHA-256 algorithm and secret key, and base64 encoded before it's added to the request. The code below is a hashing example in .NET.

    var secretKey = "m9E9pk999m9LyZ99JFNgCVb3gz8Ixojy";
    
    // Create Message, Notice Upper Case And Ampersands Seperating Parameters
    var message = "999A99HE0TR297&GET&2012-09-27T20:33:55.3564453Z&/api/v1/eVENTS".ToUpper(); 

    var key = Encoding.UTF8.GetBytes(secretKey);
    string hashString;
    
    // Create HMAC-SHA 256 Algorithm With Secret Key
    using (var hmac = new HMACSHA256(key))
    {
        // Compute Hash From Message
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
    
        // Base 64 Encode
        hashString = Convert.ToBase64String(hash);
    }
    
    // Return Hashed Message
    return hashString;

Authentication Header Format

{API KEY}.{SIGNATURE}

Authentication Header Example

999a99he0TR297.qEOgRhIYrXD/vPIL7AJh14lvCGGv4VVAS4ATjqCNtUo=

Authentication and Timestamp Header

After the signature is created the last thing to do is add the timestamp and authentication headers to the request. The example below is a web request with timestamp header in .NET.

    var headers = new NameValueCollection
    {
        { "Timestamp", "2012-09-27T20:33:55.3564453Z" },
        { "Authentication", "999a99he0TR297.qEOgRhIYrXD/vPIL7AJh14lvCGGv4VVAS4ATjqCNtUo=" }
    };
    
    var req = WebRequest.Create("https://baseball.exposureevents.com/api/v1/events") as HttpWebRequest;
    req.Headers.Add(headers);

Requests and Responses

Requests and responses currently support JSON and XML, with JSON being default.

Format

When you make an API request, the response is determined by the Accept header, while the request is determined by the Content-Type header of the request. The following accept and content-type headers are available:

JSON

application/json

JSON

text/json

XML

application/xml

XML

text/xml

Request Header

• JSON
• XML

    GET /api/v1/events
    Timestamp: 2012-09-27T20:33:55.3564453Z
    Host: baseball.exposureevents.com
    Accept: application/json
    Content-Type: application/json

    GET /api/v1/events
    Timestamp: 2012-09-27T20:33:55.3564453Z
    Host: baseball.exposureevents.com
    Accept: application/xml
    Content-Type: application/xml

Request

The request determines what to accept by looking at the Content-Type header.

• GET requests retrieve resources.
• POST requests add resources.
• PUT requests update or perform some other action on a resource.
• DELETE requests delete a resource.
• SECURE requests require HTTPS.

• JSON
• XML

    {
      "Id": 1,
      "HomeTeamScore": null,
      "HomeTeamScore": null
    }

    <Request>
      <Id>1</Id>
      <AwayTeamScore></AwayTeamScore>
      <HomeTeamScore></HomeTeamScore>
    </Request>

Response

• JSON
• XML

    {
      "Event": {
        "Id": 30,
        "Name": "adidas Super 64",
        "Notes": null,
        "Image": "https://baseball.exposureevents.com/Assets/Images/973",
        "StartDate": "7/25/2012",
        "EndDate": "7/29/2012",
        "Address": {
          "StreetAddress": "1900 Searless Avenue",
          "ExtendedAddress": null,
          "City": "Las Vegas",
          "StateRegion": "NV",
          "PostalCode": "89101"
        },
        "Divisions": [],
        "Assets": [],
        "Venues": [],
        "Prices": [],
      }
    }

    <Response xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <Event>
        <Address>
          <City>Las Vegas</City>
          <PostalCode>89101</PostalCode>
          <StateRegion>NV</StateRegion>
          <StreetAddress>1900 Searless Avenue</StreetAddress>
        </Address>
        <Assets />
        <Description></Description>
        <Divisions />
        <EndDate>7/29/2012</EndDate>
        <Venues />
        <Id>30</Id>
        <Image>https://baseball.exposureevents.com/Assets/Images/973</Image>
        <Name>adidas Super 64</Name>
        <Notes></Notes>
        <Prices />
        <Settings>
          <DisplayStateWithTeam>false</DisplayStateWithTeam>
          <EnableRegistration>false</EnableRegistration>
          <PoolTeamStatus>2</PoolTeamStatus>
          <RegistrationStatus>1</RegistrationStatus>
        </Settings>
        <StartDate>7/25/2012</StartDate>
      </Event>
    </Response>

Images

When a resource contains an image URL it can be resized dynamically by adding the querystring "h" for height or "w" for width. If both querystrings are added then the image will resize to fit within those dimenisons.

Example

https://baseball.exposureevents.com/assets/images/100?h=120&w=120

Request Parameters

Reports

Reports and brackets have an option to modify the output of the request to html or pdf, and an option to have it be viewable or downloadable. For brackets, you can show the original bracket without results.

Example

GET https://baseball.exposureevents.com/events/pools/3143?output=pdf&download=true&results=true

Request Parameters

Testing

GET requests can be tested in the browser. The user must be authenticated to the site, the url must be sent over SSL (https) and the api key needs to be appended to the request url.

Example

GET httpss://baseball.exposureevents.com/api/v1/events?id=30&apikey=999A99HE0TR297

Request Parameters

Note: You can request fresh data for testing by appending a query string of r=1 where 1 is any random number. This should only be used for testing and not a live environment. We will monitor API calls to verify this is not being implemented during a real event.