NAV
Curl Example Response

Introduction

Welcome to the Sumocard.io. You can utilize our API endpoints to get data regarding the site as well as interact with our system. We provide Japanese language dictionary services to all our users. Along with this, you have the ability to manage Word Packs for use with the SRS Web Service sumocard.io. This system is a general REST type API which provides endpoints which may support PUT, GET, DELETE, or POST methods.

We provide endpoint examples in Curl.

A note regarding example code

Our example code should be treated as stubs and not “production ready”. These only serve as functional examples to help you gain a basic understanding of how to interact with our API using a few common programming languages. For your use, these should be properly abstracted based on your language of choice. Behavior such as advanced error management/processing and logging are typically not included in our examples. However, all of the examples are working programs and as such can be tested locally. Below are the versions of software we’ve tested these examples on:

cURL 7.29.0

Authentication

We use HTTP Headers to perform the authentication and access controls for the API. A key comes as a pair, a ‘Key’ and a ‘Secret’. All of our keys have an expiration date as a security measure. To use your authentication key-pair, send the Key and Secret as headers for the request identified by ‘X-Sumocard-Key’ and ‘X-Sumocard-Secret’ respectively. For example, if your pair was:

Key: MySecretKey Secret: MySecret

then the API request must include the headers:

X-Sumocard-Key: MySecretKey X-Sumocard-Secret: MySecret

Access restrictions

You may only use your key. If you are developing another system or need a developer type key, please contact us. We are more than willing to share our data, we just need to make sure that we are not violation any of our license restrictions by doing so.

Access is metered and you are only allowed a maximum of 50 requests per second. If this access rate is exceeded, this may lead to suspension of your API key and in extreme cases, mandatory traffic mitigation.

Diagnostics / Testing

echo

#POST
curl "https://www.sumocard.io/api/alpha/echo" \
    -H "X-Sumocard-Key:yourkey" \
    -H "X-Sumocard-Secret:yoursecret" \
    -H "Content-Type: application/json" \
    -d '{"Test_Value_0" : 0, "Ping?" : "Pong!"}'
{"Test_Value_0":0, "Ping?" : "Pong"}

This endpoint is a diagnostic utility to verify communication between your system and our API.

HTTP Request

Versions: alpha

POST https://www.sumocard.io/api/alpha/echo

This endpoint will return a default message when called using GET and when using POST it will echo the request payload back to you. This serves to prove connectivity and assist with basic troubleshooting.

Dictionary Services

query

#GET
curl "https://www.sumocard.io/api/alpha/query?q=場合" \
    -H "X-Sumocard-Key:yourkey" \
    -H "X-Sumocard-Secret:yoursecret" \
[2199]

This endpoint allows you to check if a word is in our dictionary.

HTTP Request

Versions: alpha

GET https://www.sumocard.io/api/query?q=<query>

When called in GET mode, the endpoint returns the word ID numbers that match the query. You can retrieve the full word data by calling the dict Endpoint in GET mode. The result is a list of integers. To specify an exact reading, format your query as Kanji:Reading (example: 日:にち or 山：やま)

dict

#GET
curl "https://www.sumocard.io/api/alpha/dict?id=155" \
    -H "X-Sumocard-Key:yourkey" \
    -H "X-Sumocard-Secret:yoursecret" \
{
    "KanaOnly": false,
    "is_common": true,
    "tags": [
        "wanikani12"
    ],
    "japanese": [
        {
            "Id": 155,
            "word": "着る",
            "reading": "きる"
        },
        {
            "Id": 0,
            "word": "著る",
            "reading": "きる"
        }
    ],
    "senses": [
        {
            "english_definitions": [
                "to wear (in modern Japanese, from the shoulders down)",
                "to put on"
            ],
            "parts_of_speech": [
                "Ichidan verb",
                "Transitive verb"
            ],
            "tags": null
        },
        {
            "english_definitions": [
                "to bear (guilt, etc.)"
            ],
            "parts_of_speech": [
                "Ichidan verb",
                "Transitive verb"
            ],
            "tags": null
        }
    ],
    "attribution": {
        "jmdict": true,
        "jmnedict": false
    },
    "sourceUrl": "http://www.jisho.org/word/着る"
}

This endpoint allows you to request data from our dictionary service.

HTTP Request

Versions: alpha

GET https://www.sumocard.io/api/dict?id=<word_id>

When called in GET mode, the endpoint returns the dictionary record of the corresponding word_id.

dictStats

#GET
curl "https://www.sumocard.io/api/alpha/dictStats" \
    -H "X-Sumocard-Key:yourkey" \
    -H "X-Sumocard-Secret:yoursecret" \
{
    "DictSize": 2265,
    "SenseSize": 12821,
    "PartSize": 47,
    "EnglishSize": 9700,
    "AltSize": 1874
}

This endpoint provides statistics for the dictionary. This allows for us to meter and manage the growth of the dictionary.

Versions: alpha

GET https://www.sumocard.io/api/dictStats

This returns the current statistics for the dictionary.

User Services

favorite

#GET
curl "https://www.sumocard.io/api/alpha/favorite?id=155" \
    -H "X-Sumocard-Key:yourkey" \
    -H "X-Sumocard-Secret:yoursecret" \
{
    "UserId": 1,
    "WordUid": 155,
    "Correct": 98,
    "Total": 102,
    "History": "◯◯◯◯◯◯✖✖",
    "HistList": [
        9711,
        9711,
        9711,
        9711,
        9711,
        9711,
        10006,
        10006
    ],
    "NextQuiz": 1549738054,
    "RankId": 600,
    "Rank": "横綱",
    "PromotionFlag": 0,
    "DemotionFlag": 0,
    "LastWrong": 1540757790,
    "LastSeen": 1532578098,
    "TotalSeconds": 2018.7415771484375,
    "AvgSeconds": 19.791584014892578,
    "Pct": 96.07843137254902,
    "WrongThisQuiz": false,
    "Favorite": 1
}

This endpoint either adds or removes a word to a users favorites list. Accessing the favorites list is via the Favorites data provided by the user endpoint. This endpoint operates by “flipping” the bit of the Favorite flag. If the word is already a favorite, it will be turned off and if it is not, it will be set.

user

#GET
curl "https://www.sumocard.io/api/alpha/user" \
    -H "X-Sumocard-Key:yourkey" \
    -H "X-Sumocard-Secret:yoursecret" \
{
    "Id": 1,
    "Username": "sumosam",
    "Email": "sumosam@sumocard.io",
    "EncPw": "",
    "ActiveCt": 1529,
    "TotalCt": 2249,
    "AwaitingQuiz": 910,
    "MaxQuizSize": 10,
    "WorstWords": [
        1258,
        2124,
        1938,
        1939
    ],
    "Favorites": [
        1587,
        1599,
        1592,
        1919
    ],
    "EmailCommPref": 0,
    "DarkMode": 1,
    "ApiCode": "XXXXXXXX",
    "ApiEncKey": "",
    "QuizStrat": "hard_first",
    "RecoveryData": ""
}

This endpoint allows you to retrieve the user data associated with the key you submitted.

HTTP Request

Versions: alpha

GET https://www.sumocard.io/api/user

This provides basic information about the user who submitted the request. This endpoint is intended to be used to provide validation that a provided API key is valid and operational. You are only allowed to access information about the account which created the API Key.

Word Package Services

word_pack_list

#GET
curl "https://www.sumocard.io/api/alpha/user" \
    -H "X-Sumocard-Key:yourkey" \
    -H "X-Sumocard-Secret:yoursecret" \
[
    {
        "PackId": 76,
        "PackTitle": "Example Test 2",
        "WordList": null,
        "WordCache": [
            773,
            2298
        ],
        "Public": true,
        "OwnerId": 4,
        "OwnerName": "",
        "SourceUrl": "",
        "LastUpdate": 1559239341,
        "Subscribed": "",
        "IsOwner": false,
        "WordCount": 2,
        "PowerRank": 0,
        "AddWordCt": 0,
        "AddOk": false
    },
    {
        "PackId": 73,
        "PackTitle": "小っちゃな大福",
        "WordList": null,
        "WordCache": [
            253,
            578,
            688,
            895,
            924,
            2290,
            2291,
            2292,
            2293,
            2294
        ],
        "Public": true,
        "OwnerId": 4,
        "OwnerName": "",
        "SourceUrl": "",
        "LastUpdate": 1548305409,
        "Subscribed": "",
        "IsOwner": false,
        "WordCount": 34,
        "PowerRank": 0,
        "AddWordCt": 0,
        "AddOk": false
    }
]

This endpoint allows you to retrieve the word packs you have created.

HTTP Request

Versions: alpha

GET https://www.sumocard.io/api/word_pack_list

Some of the fields are not completed, AddWordCt, PowerRank, AddOk, OwnerName and Subscribed are not completed. We will add this functionality in the future if needed. This is really to be used to view your word packs and see which words are in them.

pack

#POST
curl "https://www.sumocard.io/api/alpha/pack" \
	-X POST \
    -H "X-Sumocard-Key:yourkey" \
    -H "X-Sumocard-Secret:yoursecret" \
	-H "Content-Type: application/json" \
	-d '{"PackId":74,"WordId": 155}'

#DELETE
curl "https://www.sumocard.io/api/alpha/pack" \
    -X DELETE \
    -H "X-Sumocard-Key:yourkey" \
    -H "X-Sumocard-Secret:yoursecret" \
    -H "Content-Type: application/json" \
    -d '{"PackId":74}'
#POST
{"PackId":74, "WordId": 155}

#DELETE
{"PackId":74}

This endpoint allows you to add words to a pack or delete an entire pack.

HTTP Request

Versions: alpha

POST https://www.sumocard.io/api/pack DELETE https://www.sumocard.io/api/pack

When called as a post, put the PackId and WordId in the body to add the word to the package. When called as a delete, put the PackId in the body This will delete the entire pack from the system. Be Careful!!

Errors

How we send errors

Because some developers and systems handle REST API integration various ways, we provide two methods for the transmission of errors from the API. You can either choose to have the API return ‘proper’ HTTP error codes (400, 403, 404, 405, 500) or you can choose for the Server to return a 200 OK code whenever the API is reached, regardless of the transactions status, and parse the json response to handle and parse the error message. The default behavior is the transmission of the correct HTTP status codes. To enable 200 for everything mode you send a header labeled ‘X-Sumocard-200-FOR-ALL=1’ this will make the API return every request with a 200 and any error numbers and descriptions in the message body.

In normal mode, the following HTTP codes are implemented:

HTTP Code Meaning
200 OK (The operation completed ok).
400 Bad Request - Your client submitted a malformed or invalid request.
401 Unauthorized - Your API Key is invalid.
403 Forbidden - The access credentials associated with your API key do not match the minimum required for the request.
404 Not Found - The endpoint for your request does not exist.
405 Method Not Allowed - The method for the endpoint you requested is not supported.
500 Internal Server Error - The server had an issue or error processing your request. Please try again later.
503 Service Unavailable - We are off-line for maintenance. Try again later.

Error codes / messages

We try as best as we can to create clear and concise error codes and messages. Specific error codes for the Sumocard API begin at 1000 and are allocated in blocks by endpoint. Any error code that is three digits long that you see in our system will be an HTTP error/status code.

Error Code Endpoint Meaning
Curl Example Response