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 Keys

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.

.NET

Download

Authentication

Each API request must contain a timestamp and authentication header. These ensure the request was sent by you and not a third party.

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 UTC date, RFC1123 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 (http://basketball.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 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("http://basketball.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


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


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

Request

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


    {
      "Id": 1,
      "HomeTeamScore": null,
      "HomeTeamScore": null
      "AwayTeamForfeited": false,
      "HomeTeamForfeited": false
    }


    <Request>
      <Id>1</Id>
      <AwayTeamScore></AwayTeamScore>
      <HomeTeamScore></HomeTeamScore>
      <AwayTeamForfeited>false</AwayTeamForfeited>
      <HomeTeamForfeited>false</HomeTeamForfeited>
    </Request>

Response

Note: If a value is null it is removed from the JSON or XML response.

    {
      "Event": {
        "Id": 30,
        "Name": "adidas Super 64",
        "Notes": null,
        "Image": "http://basketball.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>http://basketball.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

http://basketball.exposureevents.com/assets/images/100?h=120&w=120

Request Parameters

Name Column Names Type Default Required Description
w string The width of the image to be resized to.
h string The height of the image to be resized to.

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 http://basketball.exposureevents.com/events/pools/3143?output=pdf&download=true&results=true

Request Parameters

Name Column Names Type Default Required Description
output enumeration html The output of the response.
download boolean false The request would download the file to the client system.
results boolean true Hide or show results in a bracket.
print boolean true Hide or show print dialog for PDF.
pagebreak boolean true Avoids page breaks.

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 https://basketball.exposureevents.com/api/v1/events?id=30&apikey=999A99HE0TR297

Request Parameters

Name Column Names Type Default Required Description
apikey string The user account API key.

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.

YOUTH BASKETBALL EVENT, TOURNAMENT AND LEAGUE DIRECTORY Market your event by submitting it to our directory. Submit Event