SquashLevels connection

How to join the community

Overview

In order for SquashLevels to be a fully inclusive system it needs player details and match results from all players. We already have quite a few systems sending us results from events, leagues and boxes (see the community overview page. for details) and are actively working with others to bring them on line as well.

There are good reasons to get connected:

  • Your results will be on the system giving you a combined history of all your results wherever you played. That could be from a number of different leagues, county tournaments and even PSA events. They're all there together on one system.
  • You will have a level and detailed, graphical level history. No other system calculates 'current level of ability' to this level of accuracy.
  • You will be part of a very large community of like-minded squash players.
  • You will be able to compare yourself with anyone else in the country that plays squash - and who also has results on the system. So you could travel to a different county and know which box to join or which team to sign up for or just who to have a good game with without all those painful 'how good are you?' conversations.
  • England Squash and Racketball use the participation data to justify their funding. You will be helping a greater cause!

Note that we're trying to hard to link all systems together using ESR membership number as this is a unique number available to all players across the country. See linkage information below on how to include ESR membership number with player results.

It's surprisingly easy to get connected so please ask your webmaster to take a look at the guidelines below, get can get in touch with us and we'll have you on board in no time!

Automated upload of results

The is the first step of being able to pull your results from the system that collects them. That system (such as a league management system or internal club boxes system) needs to add a special web page that has the most recent results (and any that have been updated recently) in CSV format.

SquashLevels just opens that page each night and reads the results in. Simple! We normally advise some undocumented parameters to keep the data unavailable to unauthorised systems but these are also simple. Here's an example from BADsquash. Just click here to view.

Each row represents a single match result between two players. Each column contains the data for each of the players, the result and the type of match. If data about a player is received then that player's information on the system can be updated. That way, player data can be maintained by the source system without individual players having to maintain it themselves. Provide as much of the following data as you have available on the source system:

  • Date - Date of the match. E.g. 2014-12-19. Month in the middle please.
  • Time - Time of the match. E.g. 19:30:00. Defaults to 19:00:00.
  • Player1 - name of the first player. E.g. John Smith. Name will be auto-capitalised.
  • ID1 - ID of the first player on the source system. E.g. 326. Used to ensure results go to correct player.
  • ESM1 - ESR membership number of the first player. E.g. 6005472.
  • Club1 - Club of the first player. E.g. David Lloyd Grimsby. New clubs will be added as they are encountered.
  • County1 - County of the first player. E.g. Avon. Will be auto-abbreviated to ES standard county names.
  • Country1 - Country of the first player. E.g. ENG. Will be left blank if not available.
  • Category1 - Age group of the first player. E.g. O45. Will update if older but not younger!
  • Sex1 - Male or female for the first player.
  • DoB1 - Date of birth for first player. E.g 1983-04-20. Note this is stored encrypted and not accessible by anyone.
  • Player2 - Same fields as above but for the second player.
  • Results - Points scores if available otherwise game scores. Need pairs of numbers. E.g. "9-5, 9-7, 10-8".
  • Matchtype - Type of match in text. E.g. Surrey Mens League 2014/15. Name will be parsed and abbreviated and re-ordered to maintain consistency across the system.
  • MatchtypeID - ID of the match type on the source system. E.g. 74.
  • FixtureID - ID of the match/fixture ID on the source system. Needs to be unique for every match and is used to identify a match that's being updated rather than a new one. If you use the same fixture ID for all the strings then multiply by 10 and add the string number to make them unique. E.g. 493074.

Ideally the source system can provide all of this information but SquashLevels will assume players are senior, males with no country or ESM number. MatchtypeID and FixtureID are also optional. The remaining fields are mandatory.

Note that information about the players can be derived from the match type such as Mens O45 is for O45. Or York Ladies is for ladies!

Inter-linking the community systems

So that the systems form a community for the players (and not just a set of isolated systems) there should be two way links between the source systems and SquashLevels. This is part of the requirements of getting connected.

If possible, players should be referenced using their ES&R membership number allowing all systems to use the same reference for players. If the ES&R number is not available then systems should use their own ID along with the reference name of their system. All source systems are allocated a name when they link up.

Links from SquashLevels to the source systems

These links provide single click access back to the source systems allowing the players fast access to the pages that are of most interest and specific to them. If you have a page you'd like us to link to them please let us know.

  • From the player history page to the equivalent source system player detail page.
  • From the Community page to the home page of the source system.
  • From the Community page to a page of the source system advertising it's features in detail along with contact numbers and anything else you'd like to have - it's your page.
  • The community page will also list and summarise the features of all the connected source systems (you'll need to give us the content!).

If you have a logo URL we would like to use it!

Links from the source systems to SquashLevels

These links provide single click access to SquashLevels pages of most interest to the players such as rankings and player history. Note that any links can be used but page content will depend on whether the player has previously logged on to SquashLevels. If so then then full page content will be available otherwise it will be slightly reduced. This feature relies on the player using cookies.

These links work well from the source system home page.

  • SquashLevels home page. Use www.squashlevels.com.
  • County or league rankings. Any ranking list available on SquashLevels can be linked to using your source system name as a reference. Use www.squashlevels.com/players.php?all&source=<source name>&list=county. Click here for example.

Please use our logo URL at www.squashlevels.com/images/squashlevels.png with your links.

These links work well from the source system player detail page.

  • Player history. Use www.squashlevels.com/player_detail.php?player=<source player ID>&source=<source name>. Click here for example.
  • Club rankings with player highlighted. Use www.squashlevels.com/players.php?all&player=<source player ID>&source=<source name>&list=club. Click here for example. Non members will not have their position highlighted.
  • County rankings with player highlighted. Use www.squashlevels.com/players.php?all&player=<source player ID>&source=<source name>&list=county. Click here for example. Non members will not have their position highlighted

Access to SquashLevels data using the REST API

Many of the user readable web pages on SquashLevels can be returned in JSON format for system consumption by adding the parameter format=json. All parameters are passed in using the GET method - which is the equivalent of typing in the URL on your browser. E.g. www.squashlevels.com/players.php?all&source=<source name>&list=county&format=json. Click here for an example.

The data is returned as a JSON list with value:ID pairs for each piece of data. This allows source systems to include the SquashLevels ranking lists directly on their own pages.

JSON structure

All returned JSON structures use the following format:

{"status":"<good/bad/warn>",
"message":"<Text message explaining result or failure>",
"user_message":"<Text message for the user - generic news or telling them that they need to be a member>",
"data":{<returned data>}}

The message text is mainly to use if something goes wrong - it will tell you what. The user text message is to show the user. This might be generic news such as system downtime planned (not that we ever take it down) or, more likely, that the feature they're asking for needs them to be logged on as a member. Mostly, this user message will be blank. The data that was requested will be returned in the 'data' field.

Player listings (rankings)

The players.php page is used for player listings for both the web page and JSON output. The listings are controlled using the following parameters:

  • all - No value needed. Turn everything on (all filters off). Shorthand for setting all the other parameters to 'all'.
  • show - Use [last10/last6m/last12m/last24m/all]. The time period to search over. Need to be a member to see more than 12 months.
  • club - Use clubid as defined by SquashLevels. See below for access to the clubids.
  • player - Use playerid as defined by SquashLevels to list a single player only. If source is set then use the playerid of the source system. If list is set as well then defer to list description below instead.
  • county - Use countyid as defined by SquashLevels. See below for access to the countyids.
  • country - Use countryid as defined by SquashLevels.
  • matchtype - Use matchtypeid as defined by SquashLevels.
  • playertype - Use [male/female/all].
  • playercat - Use [U13/U17/.../O35/O45/.../Senior/Pro/etc.]. See filter pull-downs on web page for full list.
  • events - Minimum number of events played.
  • search - For searching by player name. Use name snippets such as jon+sm+th
  • min - Minimum level to show
  • max - Maximum level to show - use these to show players within a range of levels
  • start - Start position to show
  • perpage - Number of players per page to show - use these to step through multiple pages of player listings
  • highlight - Start the listing 10 players before the requested playerID. For highlighting the player in a ranking list. Members only.
  • grade - [0/1]. Use to include the player's grade column or not. Default off. Grade is specific to Avon events.
  • confidence - [0/1]. Use to include the level confidence column or not. Default off.
  • limit_confidence - [0/1]. Use to include the level confidence column or not. Default on.
  • source - Limit the results to those from your system.
  • sourceid - As above but use the ID rather than name.
  • source_playerid - When source is set, you can use this to identify a player from your system using your ID. Same as using player (above) but offered for consistency.
  • list - Use with source and player. Set to club to see the player's club listing or county to see the player's county listing. Supports the single click player rankings links from the source system.
  • source_matchtypeid - Use the matchtypeid from the source system. Source needs to be set for this to be used and the value must have been passed in with the results.
  • format - Use json for JSON output. Defaults to web output.

The defaults are set to list all players for the last 12 months with no other restrictions but they can be overridden by cookies which are set to the filters used for the last player listings selected. This allows users to set up the player listings that they want to see and then that's what they'll always see if they don't change it.

Access to club and county IDs

It may help to be able to list the full set of club and county IDs used by the system. They are dynamically added to but once defined, not normally changed (unless duplicated clubs are merged). Use the following page for JSON output:

http://www.squashlevels.com/info.php?action=list_clubs&format=json

Finding out processing state and results upload history

If you intend to cache any data locally to your own system, you should be aware that SquashLevels reprocesses its levels over night and may have made changes during that process. You can use the URL below to return a JSON structure that will tell you what the processing state currently is and when it last changed state. The state is shown as 'completed' at the end of processing. You can use this to determine when to refresh your cached data.

http://www.squashlevels.com/info.php?action=process_summary&format=json

This URL also returns a summary of the uploaded results for the last 7 days. You will find a structure showing the upload count for each source/matchtype/date combination for the last 7 days. You should be able to find out how many results SquashLevels has received from your system using this structure.