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. Thesecret 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
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.
{
"Id": 1,
"HomeTeamScore": null,
"HomeTeamScore": null
}
<Request>
<Id>1</Id>
<AwayTeamScore></AwayTeamScore>
<HomeTeamScore></HomeTeamScore>
</Request>
Response
null
it is removed from the JSON or XML response.
{
"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
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 https://baseball.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. | ||
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 httpss://baseball.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.