High Score API Free

A simple free API service. It allows you to save/retrieve Daily, Weekly and Monthly high scores. It is intended for adding high score list to a web game, but it could be used for other purposes. It stores 10 high scores.

Implementation examples: Snake - Onion Man and His Stars.

This server is an open source project: https://github.com/marusasa/high-score-server

Feedback: Please open an 'issue' here.

My Blog.

How to use it:

Account creation and high score list creation is all done by calling HTTP APIs.

1. Create Account

In order to user this service and to create an account, you must agree to the following user agreement.

User Agreement:
User agrees that this service is provided as is without any guarantee.
User agrees that this service will be used for hobby projects only.
In no event shall the service owner be liable for any damages arising out of the use or inability to use the service.				

If you agree to the above user agreement, type 'I agree to the user agreement' in the 'agreement' field.

'name' and 'email' is optional.

URL: https://highscore.sasagu.com/api/v1/create-account
HTTP Method: POST
HTTP Header: 'Content-Type: application/json' 
HTTP Body:
{
	"name": "YOUR FULL NAME",
	"email": "your@emailaddress",
	"agreement": ""
}

Result:

{
    "errors": [],
    "success": true,
    "message": "Save the account_id. Use it to create a high score table. Use the same account_id when creating multiple high score tables.",
    "account_id": "cbd8b9f8-4ef4-4e4f-bc70-1e4bf9a1541d"
}

account_id must be kept private. Do not share it with anyone.

3. Create High Score Table

Use your account_id to create a high score table.

For 'type' use one of the following:

Type	Description
D	Daily. Data gets cleared daily at 1AM Pacific Standard Time.
W	Weekly. Data gets cleared weekly at every Monday 1AM Pacific Standard Time.
M	Monthly. Data gets cleared monthly at 1st day of Month at 1AM Pacific Standard Time.

Use this to create a high score table record.

URL: https://highscore.sasagu.com/api/v1/create-highscore
HTTP Method: POST
HTTP Header: 'Content-Type: application/json' 
HTTP Body:
{
    "account_id": "cbd8b9f8-4ef4-4e4f-bc70-1e4bf9a1541d",
    "name": "Sample High Score - Weekly",
    "type": "W"
}

Result:

{
    "errors": [],
    "success": true,
    "message": "Save the highscore_id. Use it to add/get/clear scores.",
    "highscore_id": "c60bf258-3103-42eb-8800-703894d759e2",
    "account_id": "cbd8b9f8-4ef4-4e4f-bc70-1e4bf9a1541d"
}

'highscore_id' will be used in your program when saving/displaying high scores.

3. High Score Management

In most cases, the easiest way to integrate the APIs into your game is to use a JavaScript component ssg-high-score.js. This is a component used by the reference projects mentioned above. View the github page to lean how to use it.

4. High Score API

If you choose not to use high-socre-js component, you can use the following api's to update the high score boards.

Scores

Use this to get scores.

URL: https://highscore.sasagu.com/api/v1/scores/[highscore_id]
HTTP Method: GET

Result:

{
    "errors": [],
    "success": true,
    "scores": [
        {
            "score": 50,
            "name": "JOHN"
        },
        {
            "score": 10,
            "name": "Test"
        }
    ],
    "score_to_keep": 10,
    "bottom_score": 0,		//This scores the lowest score of the list. 0 indicates any score can be added.
    "top_score": 50,		//This indicates the highest score.
    "score_count": 2,		//count of scores in the list.
    "game_name": "Sample High Score - Weekly"
}

Add Score

Use this to add a new high score to the board.

URL: https://highscore.sasagu.com/api/v1/add-score
HTTP Method: POST
HTTP Header: 'Content-Type: application/json' 
HTTP Body:
{
    "highscore_id": "6f70f9fd-c992-4be9-b70b-82b45e5c0bb8",
    "name": "JOHN",
    "score": 50
}

Result:

{
    "errors": [],
    "success": true,
    "scores": [				//the result includes the updated high score list.
        {
            "score": 50,
            "name": "JOHN"
        },
        {
            "score": 10,
            "name": "MICHAEL"
        }
    ],
    "score_to_keep": 10,
    "bottom_score": 0,
    "top_score": 50,
    "score_count": 2,
    "game_name": "Sample High Score - Weekly"
}

Clear Board

Use this only when you want to manually clear the scores.

URL: https://highscore.sasagu.com/api/v1/clear-scores
HTTP Method: POST
HTTP Header: 'Content-Type: application/json' 
HTTP Body:
{
    "account_id" : "a2809085-39a6-4d42-9762-7efda03a0530",
    "highscore_id": "6f70f9fd-c992-4be9-b70b-82b45e5c0bb8"
}

Result:

{
    "errors": [],
    "success": true
}