API docs

API documentation for the Scrollsguide Scrolls API. All calls are made using the GET-method. Responses are formatted using JSON unless stated otherwise. The msg value in the JSON response indicates whether or not the operation was successful. If a request was successful, the data value in the response contains the data of the request. The courtesy rate limit is at one request per second, but you will not be throttled until a much higher number of requests. If you are using the Scrollsguide API in a public application, please provide a link to Scrollsguide for all the work we put into keeping it up-to-date :).

Setting the d parameter will include the execution time in ms in the output.

Online player number

Gets the number of online players.
Request url:http://a.scrollsguide.com/online
Parameters:
time
Optional. Setting this parameter will include the cache time in the output.
Example request:
Cache:Cached for 1 minute.

Overall game statistics

Gets the overall game statistics which can be seen on the splash screen of Scrolls. Note: the gamesplayed and totalusers data is not retrieved from official sources and is calculated by Scrollsguide.
Request url:http://a.scrollsguide.com/statistics
Parameters:
time
Optional. Setting this parameter will include the cache time in the output.
Example request:
Cache:Cached for 10 minutes.

Scrolls

Gets the full details on the available scrolls in the game. Includes unofficial information such as the version code for the version the scroll was introduced in.
Request url:http://a.scrollsguide.com/scrolls
Parameters:
name
Optional. Name of the scroll to retrieve information for.
id
Optional. Comma-separated list of scroll ids to retrieve information for. Not setting this parameter will retrieve all scrolls.
versions
Optional. Setting this parameter retrieves scroll id and version for all scrolls. The version is an integer incremented by 1 every time any statistic for the scroll changes. Use this number to check whether a scroll needs updating, if you're running a local copy of the scrolls database.
norules
Optional. Setting this parameter won't retrieve the passiverules and abilities for the scrolls, making the request a bit lighter, thank you :) .
Example requests:
Cache:Cached until a Scrolls update.

Scroll images

Gets the full in-game image for a scroll, with statistics and description. Note: these images are generated, the information on them is always correct, however measurements/alignments may be slightly off.
Request url:http://a.scrollsguide.com/image/screen
Parameters:
name
Required.Urlencoded name of the scroll to get the image for. Case insensitive.
size
Optional. Size of the returned image. Defaults to small, possible values are small, large.
Example request:
Cache:Cached until any value of the scroll has changed.

Player statistics

Gets the in-game statistics for a player.
Request url:http://a.scrollsguide.com/player
Parameters:
name
Required.Required. In-game name of the player, case insensitive.
fields
Optional. Comma-separated list of fields to retrieve. Defaults to name,rating. Possible values are
name - in-game name, correctly capitalized
rating - rating, updated instantly
rank - rank, recalculated every 10 minutes using the player's rating
badgerank - rank id for matching against the ranks request.
played - number of games played
won - number of games won
rankedwon - number of ranked games won
limitedwon - number of limited games won
surrendered - number of games surrendered (calculate games lost using lost = played - won - surrendered)
gold - amount of gold the player has
scrolls - amount of scrolls the player has
lastgame - number of seconds since this player's last game. -1 if the player hasn't played a game yet
lastupdate - number of seconds since this player's statistics were updated, excluding rank. Usually this is the last time the player has logged in.
all - retrieves all of the above fields.
achievements
Optional. Setting this parameter will include a user's achievements in the result. This includes the id of the achievement, as well as the time the user achieved it.
avatar
Optional. Setting this parameter will include the user's avatar settings in the result.
Example requests:
Cache:Not cached.

Ranking

Gets the in-game ranking. List is ordered by in-game rating which is updated instantly if changed for a player.
Request url:http://a.scrollsguide.com/ranking
Parameters:
start
Optional. Row number to start retrieving from. Defaults to 0.
limit
Optional. Number of rows to retrieve. Defaults to 100, maximum value is 500.
sort
Optional. Sorting order of the list. Defaults to desc, possible values are asc, desc.
fields
Optional. Fields to retrieve for each player in the listing. See fields for player requests.
Example request:
Cache:Cached for 5 minutes.

Player graphs

Gets the graph for a player's rating or gold progression over the past days. Returns array of JSON objects with three keys for rating: d, for number of days ago, where "d":0 is today, and "d":1 is yesterday and so on. t is the highest rating the player reached on that day, b is the lowest rating.
Note: this request fails if either the player does not exist, or hasn't logged in to Scrolls in the past days days.
Request url:http://a.scrollsguide.com/graph
Parameters:
name
Required.Name of the user to retrieve the rating data for. Case insensitive.
type
Optional. Type of the graph. Defaults to rating. Possible values are rating, gold, scrolls.
days
Optional. Number of days to retrieve. Defaults to 14, maximum value is 30.
Example requests:
Cache:Cached for 30 minutes.

Prices

Gets the in-game prices for scrolls as parsed from the trading channel chat.
Request url:http://a.scrollsguide.com/prices
Parameters:
name
Optional. Name of the scroll to retrieve prices for.
id
Optional. Comma-separated list of scroll ids to retrieve information for. Not setting this parameter will return prices for every scroll.
details
Optional. Does not include an average buy/sell price for the scrolls, instead returns a complete list of separate offers with time, room, user and price included. "price":-1 means the offer did not include a price. Deduping is applied to the result, only displaying the last offer for each player.
days
Optional. This parameter controls for how many days back the prices should be returned. 1 means only retrieve prices from the past 24 hours while setting it to 3 retrieves prices from 72 hours back. Defaults to 2, maximum value is 10.
Example requests:
Cache:Not cached.

Achievements

Gets the in-game achievement list.
Request url:http://a.scrollsguide.com/achievements
Parameters:none
Example request:
Cache:Cached until new achievements are added to the game.

Ranks

Gets the in-game rank list.
Request url:http://a.scrollsguide.com/ranks
Parameters:none
Example request:
Cache:Cached until new ranks are added to the game.

Weekly winners

Gets the in-game weekly winners list.
Request url:http://a.scrollsguide.com/weeklywins
Parameters:none
Example request:
Cache:Cached once a week.

Mojang news list

Gets the official news feed from scrolls.com. Warning: very much in beta, images have been stripped and HTML may be altered.
Request url:http://a.scrollsguide.com/news/mojang
Parameters:
id
Optional. If id is set, this article's full content is retrieved.
start
Optional. Row number to start retrieving from. Defaults to 0.
limit
Optional. Number of rows to retrieve. Defaults to 10, maximum value is 100.
Example requests:
Cache:Scrolls.com is crawled every 12 hours.

Community guides

Gets community-written tutorials and guides for the game. These articles have been approved manually, asserting good quality.
Request url:http://a.scrollsguide.com/news/community
Parameters:
id
Optional. If id is set, this article's full content is retrieved.
start
Optional. Row number to start retrieving from. Defaults to 0.
limit
Optional. Number of rows to retrieve. Defaults to 10, maximum value is 100.
Example requests:
Cache:Not cached.

Game changelog

Gets the changelog for every version of the game up to the most recent version. This changelog lists changes made to scrolls (generated), as well as bugfixes and known issues (hand-written)
Request url:http://a.scrollsguide.com/changelog
Parameters:none
Example request:
Cache:Cached until a new release of Scrolls.