MCLA.us "Expert API" | Information & Documentation

MCLA.us "Expert API" documentation - v 1.0

Introduction

The MCLA.us "Expert API" offers web developers direct access to Official MCLA team rosters, team schedules, final game scores, and player statistics. Use of the API requires a developer be able to: create properly formatted request strings, parse request results from XML, and cache data. For developers unable to work with this API, a less technical (and less customizable) may be available in the future.

UPDATES

10/07/2009 - A "simple widget" javscript version of the API is nearing completion. If you would like to beta test it, please contact .
05/28/2009 - Off-Season Maintenance will be announced soon. API will be offline for 30-60 days in preparation for updates.
03/13/2009 - Expect a short period of maintenance in the next 24-48 hours.
02/26/2009 - Optional date range in 'game' method limited to 31 day range for performance.
02/24/2009 - Corrected improper game url in schedule method.
02/22/2009 - Major v1.0 update. API no longer in beta. Added results for completed games to schedule method - v1.0 only.
02/15/2009 - Added "game_status" to schedule method. Added "divisional_record_win" and "divisional_record_loss" to team method.
01/30/2009 - Added "game_type" to schedule method. Also, preparing for next version. See notes on passing version variable below.
01/22/2009 - Added "team_slug" (inadvertently left out of original XML response). Acceptable conference abbreviations are now listed in documentation.

Accessing the API

Developers interested in accessing MCLA data must first register for an "API Key". This is a unique 32 encoded character string identifying the user and the site running the API. Applying is currently manually done by and including 1) the site that will be making requests and 2) a contact name and email. By requesting and using this API you are agreeing to all terms of use as detailed below.

Terms of Use / Rules

By applying for an API key you agree to these Terms of Use / Rules. Refusal to follow as stated will result in your API key being temporarily or permanently disabled.

Your API Key:

Individual API keys can be disabled at the discretion of the MCLA without notification.
You are responsible for safe guarding your API key. Do not share your key with anyone.
Developers providing data to more than one site may utilize the same API key for multiple domains - if authorized.
The API request server may occasionally be disabled for maintenance. A notice will be posted here with expected return time when possible.

Branding Requirements:

All domains using this API must display the "Powered by MCLA.us" graphic in a prominent location, at least once, next to any data being provided by the API. See code.
<a href='http://mcla.us/'><img src='http://mcla.us/images/powered_by_mcla.jpg' alt='Powered by MCLA.us' /></a>
When displaying team or game info on your site, you must provide a link to the team or game URL as provided in the XML.

Usage:

Limit requests to no more than 6 per hour / 150 per day (24 hour period). Accounts exceeding this limit will be disabled immediately.
Direct web access (as seen in our examples) is disabled for all other keys.
Attempts to improperly access data, as not defined in this document, will result in your API key being temporarily or permanently disabled.
Redistribution, reselling, or transferring data retrieved via the API to a third party will result in your API key being temporarily or permanently disabled.
All requests are monitored and logged. This data is used for security of MCLA.us data only and does not contain personal information about you, your server, or your visitors.

Data:

All requests must currently be GET - not POST.
API responses are currently valid UTF-8 XML.
As a general good practice, cache data when possible. Specifically, we recommend you cache static data on your servers, such as the team list or roster, when data is not expected to change on a regular basis. Requesting data less frequently eliminates unnecessary traffic and strain on your web server as well as ours.

Versions

Utilize the 'version' variable to pass the requested API version in your request string.
The current version is v1.0. The default is currently v0.1 beta.
Game result information (scores, player stats, etc) is available in v1.0 and above.
v0.1 beta will expire on 4/1/2009 at which point the default will become v1.0.

Methods Available in v1.0

Team:

div (optional) - You may choose to specify division. Acceptable variables are "1" or "2". Default shows both.
conf (optional) - You may also choose to specify conference. See all acceptable conference abbreviations. Default shows all.
CCLA, SELC, GRLC, UMLL, PCLL, WCLL, PNCLL, RMLC, LSA, SLC

Game:

date - All dates must be in MM/DD/YYYY format.
start / end (optional) - Set a range of dates in MM/DD/YYYY format. Date range limited to 30 days.
team (optional) - Pull a single team schedule by sending the team slug (as defined in the 'show all teams' XML as "team_slug").

Roster:

team (required) - Pull a single team roster by sending the team slug (as defined in the 'show all teams' XML as "team_slug"). Note: only verified and eligible players will be shown in results.

Building a Request

Combine your API key, the desired version, a method, and additional variables and submit to the base request URL: http://api.mcla.us/request/

Example API Requests

Contact / Support

Questions, comments, complaints, limited technical support or feature requests can be sent to: .