robiningelbrecht/wca-rest-api

Unofficial World Cube Association (WCA) Public API

Unofficial World Cube Association (WCA) Public API

---

Welcome to the unofficial World Cube Association (WCA) Public API documentation! Here, you'll find all the information you need to integrate this API seamlessly into your projects. Access competition data, results, competitor profiles, rankings, and more.

Note: This API is served through static JSON files on GitHub, which means the structure of the endpoints has limitations. The reason for doing so is:

• The data doesn't change that much, max once a day
• Static file-based API is (or should be) very fast
• I don't want to pay for any hosting because it could get very expensive, very fast

The API is updated once a day so rankings and results are not real-time.

This information is based on competition results owned and maintained by the World Cube Association, published at https://www.worldcubeassociation.org/export/results as of June 02, 2024.

I'm in no way affiliated with or part of the official WCA software team.

Getting started

The full documentation and specs are available at https://wca-rest-api.robiningelbrecht.be/

Feedback

For any feature requests, help posts, or bug reports, please open an issue in the issue queue. I'll be happy to help you out.

Entity relations

To give you an idea about the relations between the entities and how you can query the API, I created the following schema:

Local development

If you'd like to help with the development of this project, or you just want to run it locally, run the following commands:

# Clone repo
> git clone [email protected]:robiningelbrecht/wca-rest-api.git
# Setup .env file
> cp .env.dist .env
# Build docker containers
> docker-compose up -d --build
# Install dependencies
> docker-compose run --rm php-cli composer install
# Build all the static API files.
> docker-compose run --rm php-cli bin/build-new-api.sh "continent,country,event,competition,championship,person,rank,result,version"

This should result in following CLI output:

Downloading WCA export...
Unzipping WCA export...
Archive:  wca-export/export.zip
  inflating: wca-export/metadata.json  
  inflating: wca-export/README.md    
  inflating: wca-export/WCA_export.sql  
Importing WCA export to database...
Building API...
  - Building continent API...
  100% [============================] 2/2 [< 1 sec]
  - Building country API...
  100% [============================] 2/2 [< 1 sec]
  - Building event API...
  100% [============================] 2/2 [< 1 sec]
  - Building competition API...
  100% [============================] 12487/12487 [1 min]
  - Building championship API...
  100% [============================] 582/582 [7 secs]
  - Building person API...
  100% [============================] 199304/199304 [51 mins]
  - Building rank API...
  100% [============================] 43/43  [24 mins]
  - Building result API...
  100% [============================] 10028/10028 [5 secs]
  - Updating API version...
Total execution time: 77 min

Test suite

When you've completed the local setup, you can run the test suite:

> docker-compose run --rm php-cli vendor/bin/phpunit

wca-rest-api's Issues

Docker compose build fails in local development

Following the guide on the readme, after running

sudo docker-compose up -d --build

this command resulted in this output:

 => [php-cli internal] load .dockerignore                                                                    0.0s
 => => transferring context: 2B                                                                              0.0s
 => [php-cli internal] load build definition from Dockerfile                                                 0.0s
 => => transferring dockerfile: 381B                                                                         0.0s
 => [php-cli internal] load metadata for docker.io/library/composer:latest                                   0.8s
 => [php-cli internal] load metadata for docker.io/library/php:8.2-cli                                       0.8s
 => CACHED [php-cli stage-0 1/4] FROM docker.io/library/php:8.2-cli@sha256:e0941c06b8a4f6e48c7c57672dce608d  0.0s
 => CACHED [php-cli] FROM docker.io/library/composer:latest@sha256:6d19e1002b091908fc4654725d4055125f181c1b  0.0s
 => ERROR [php-cli stage-0 2/4] RUN apt-get update && apt-get install -y zip unzip git curl default-mysql-c  0.0s
------
 > [php-cli stage-0 2/4] RUN apt-get update && apt-get install -y zip unzip git curl default-mysql-client libicu-dev:
------
failed to solve: process "/bin/sh -c apt-get update && apt-get install -y zip unzip git curl default-mysql-client libicu-dev" 
did not complete successfully: failed to create endpoint seq8o7cblxs6mpcqw4w6t3sui on network bridge: 
failed to add the host (vethf4b2ba4) <=> sandbox (vethb5c1d57) pair interfaces: operation not supported

Get number of records in person's schema

It would be really nice if there was a way to get the number of records a person has beaten, just like there is the medals object in the person's schema.

This info is shown in the person's wca profile (as in the print below), so I am guessing it is somewhere in the database export and can be brought to the api as well

Country should default to current, not previous country

If a person gets a subid, e.g. for changing region, there would be multiple regions that could be of interest: the former one or the current one, under which they should be ranked.

I now have a case where the API returns country 'CN' while the tsv-export of the database returns 'DE', the reason probably coming from handling the subid https://github.com/thewca/worldcubeassociation.org/blob/main/app/views/persons/_details.html.erb#L12 differently.
Could you look into this? We are using your API for a fresh federal state ranking (https://github.com/AnnikaStein/WCA-German-State-Ranks) that everyone can enter independent of the country on the WCA page, hence we sometimes have some person data with a foreign country, and in rare cases, their country changed in the past. We would like to be inclusive, and not require any condition a priori here, some people live there, study there, or have any other affiliation with a federal state that is independent of citizenship.

Example: https://annikastein.github.io/WCA-German-State-Ranks/pages/by-state_bw.html which is generated from the API writes 2018XIAO03 as 'CN', while the Website writes 'DE' as country code, same for the aforementioned tsv. 'DE' would be what we want to grab, not the previous country iso that refers to the person's subid.

It would be great to have this data being written into the country string when using person by id (https://wca-rest-api.robiningelbrecht.be/#tag/person/operation/getPersonById). Thank you and greetings!

live data api

Hi there. Let's support each other: https://github.com/h3tz/wca-api

Build API is failing

Hi @robiningelbrecht ,

I've noticed that Build API is failing for some time. Could you please take a look?
Example pipeline: https://github.com/robiningelbrecht/wca-rest-api/actions/runs/7873774609/job/21481868328

Getting images using id

Hi, I really like your project, and I'm using it to make a discord bot. And I noticed that on Max parks there is also an image (wow) but I noticed that image is following a weird structure:

image

https://avatars.worldcubeassociation.org/uploads/user/avatar/2012PARK03/1631071192.jpg

and I don't understand why there is 1631071192 at the end and i think you may know. I think it can be countered in the order the image is uploaded. But I don't know how to get that with a code. And do you know?

Thanks

Medals Counter

The medal counter shows the number of places won in all rounds in all tournaments (I also checked with other users, and it's probably true) It seems to me that this should only return the value of the final rounds

decoding 3x3 mbf

how am i supposed to decode 940239001
to 6/7 39:50 and its a 3x3 multi blindfold result
thanks and lmk if you nead additional info