-
Notifications
You must be signed in to change notification settings - Fork 86
API v0.9
Please join the Google Groups Mailing List for gw2spidy so that I can keep you up-to-date of any changes / new versions of the API!
Atm I'm focusing on getting out as much functionality, error reporting is done by returning a 404 error.
Make sure you check those headers!!
Where there are more then x amount of results (atm for the item list and the item listings this is 100) the results are paged.
Based on the current "page" in the reponse and the "last_page" you should be able to get all data ;-)
When using the API please consider that this is a hobby project created by and for the community.
If you're going to spam the API with a constant stream of requests for whatever reason, just come talk to me so we can think of a better way to provide you with what you need ;)
All datetime, date and time fields are in UTC and also contains the ' UTC' suffix, most languages should be able to flawlessly parse this, if not, strip it off ;)
If you find fields without the ' UTC' suffix or just think they are off, contact me, I might have missed one!
All prices are stored and returned as integers, you should handle converting to a 11g 22s 33c format yourself.
Incase you didn't get it yet, 100 copper = 1 silver and 100 silver = 1 gold so 112233 is 11g 22s 33c ;)
Item listings are crawled depending on their priority, some are crawled every 15 minutes, other less often, this influences the freshness of the price data of course!
All JSON responses either contain a "result" or "results" key.
"result" will always directly be an object because the used API method can only return 1 possible result
"results" will always be an array containing an x amount of objects, because it has the potential to return multiple results
To be able to maintain backwards compatibility all API methods contain a {version} argument, the following document describes how the API behaves when using v0.9 as version.
When I talk about arguments I mean whatever is /<in>/<the>/<url>.
When I talk about parameters I mean everything that ?is=added&to=the&query=string.
The API can be used to return data in the following formats:
- json
- csv
All API methods contain a {format} argument, use either of the above, undercase!
NOTE I'm not a fan of CSV and I hate XML, however I realise many people will want to use CSV for spreadsheets or other market related software so it's worth including in my API, XML will never happen though, don't bother asking :P
The documentation (for now) will be focused on JSON, the CSV output will have the same data, except the first row will be the headers of course!
When using json as format you can specify a ?jsonp=callback parameter with your chosen callback.
Or ?callback=callback will do the same (jQuery will automatically recognise it's jsonp when you do this).
Marthisdil made a short and awesome PDF guide for loading API data into MS Excel.
and Valaadus also made a very nice PDF guide for loading API data into Google Docs.
Tynril created a nice python wrapper around the API and you can find it on his github page.
I wrote a small example in PHP and you can find it in this gist
- Type List
- Discipline List
- Rarity List
- Full Item List
- Item List
- Item Data
- Item Listings
- Item Search
- Recipe List
- Recipe Data
- Current Gem Price
- Gem Price History
/api/{version}/{format}/types
* {version} - see the section about Version
* {format} - see the section about Formats
Results are cached server side for up to 24 hours
Subtypes start their IDs from 0, for every top level type, following ArenaNet's design ;)
{
"results" : [
{
"id" : 0,
"name" : "Armor",
"subtypes" : [
{
"id" : 0,
"name" : "Coat",
},
{
"id" : 1,
"name" : "Gloves",
}
{ /* subtype #3 */ },
{ /* etc ... */ }
]
},
{ /* type #2 */ },
{ /* type #3 */ },
{ /* etc ... */ }
]
}/api/{version}/{format}/disciplines
* {version} - see the section about Version
* {format} - see the section about Formats
Results are cached server side for up to 24 hours
{
"results" : [
{
"id" : 1,
"name" : "Armorsmith",
},
{ /* discipline #2 */ },
{ /* discipline #3 */ },
{ /* etc ... */ }
]
}/api/{version}/{format}/rarities
* {version} - see the section about Version
* {format} - see the section about Formats
Results are cached server side for up to 24 hours
{
"results" : [
{
"id" : 1,
"name" : "Common",
},
{
"id" : 1,
"name" : "Fine",
},
{ /* rarity #3 */ },
{ /* rarity #4 */ },
{ /* etc ... */ }
]
}/api/{version}/{format}/all-items/{type}
* {version} - see the section about Version
* {format} - see the section about Formats
* {type} - either an ID of a top level type or use *all*
Results are cached server side for up to 3 minutes
{
"count" : 100,
"results" : [
{ /* item #1 - same output as from the item data call */ },
{ /* item #2 */ },
{ /* item #3 */ },
{ /* etc ... */ }
]
}/api/{version}/{format}/items/{type}/{page}
* {version} - see the section about Version
* {format} - see the section about Formats
* {type} - either an ID of a top level type or use *all*
* {page} - page offset
?sort_trending= - either 'sale' or 'offer' to sort descending on the price change in the last hour
this also limits results to having > 200 sale and offer availability to keep it relevant
?filter_ids= - a comma seperated list of Item (Data)IDs to filter the result by
MAXIMUM amount of IDs as what fits on 1 page! which is 100 currently!
Unless you want to filter it by type, use *all* for type!
Results are cached server side for up to 15 minutes
URLs can only be ~ 2k characters long, when using ?filter_ids= with a lot of IDs it might not work and you should use POST with filter_ids= in the body!
Please use Full Item List for anything but ?filter_ids= or ?sort_trending.
This method will most likely be deprecated in later API versions because the pagination is suboptimal for me and you ;)
{
"count" : 100,
"page" : 1,
"last_page" : 24,
"results" : [
{ /* item #1 - same output as from the item data call */ },
{ /* item #2 */ },
{ /* item #3 */ },
{ /* etc ... */ }
]
}/api/{version}/{format}/item/{dataId}
* {version} - see the section about Version
* {format} - see the section about Formats
* {dataId} - the ID of the item you want to retrieve data for
Results are cached server side for up to 3 minutes
If you need high frequency of updates, this is what you want to use (and what I want you to use!).
{
"result" : {
"data_id" : 23654,
"name" : "Fake Item",
"rarity" : 3,
"restriction_level" : 72,
"img" : "http://www.url-to-offical-gw2-site.com/img.png",
"type_id" : 1,
"sub_type_id" : 2,
"price_last_changed" : "YYYY-MM-DD HH:II:SS UTC",
"max_offer_unit_price" : 6523,
"min_sale_unit_price" : 9345,
"offer_availability" : 1235232,
"sale_availability" : 203203,
"sale_price_change_last_hour" : 40, # this is the percentage the item price changed since the last hour
"offer_price_change_last_hour" : 70 # same --^ I know it ain't pretty but have to do with this for now ;)
}
}/api/{version}/{format}/listings/{dataId}/{sell-or-buy}/{page}
* {version} - see the section about Version
* {format} - see the section about Formats
* {dataId} - the ID of the item you want to retrieve listings for
* {sell-or-buy} - whether you want the sell or the buy listings, use singular and lowercase: sell or buy
* {page} - page offset
Results are cached server side for up to 15 minutes
Data is ordered descending by date/time
{
"sell-or-buy" : "sell",
"count" : 250,
"page" : 1,
"last_page" : 3,
"total" : 3,
"results" : [
{
"listing_datetime" : "YYYY-MM-DD HH:II:SS UTC",
"unit_price" : 23,
"quantity" : 7868,
"listings" : 11
},
{ /* listing #2 */ },
{ /* listing #3 */ },
{ /* etc ... */ }
]
}/api/{version}/{format}/item-search/{name}/{page}
* {version} - see the section about Version
* {format} - see the section about Formats
* {name} - the name of the item you're looking for
Results are cached server side for up to 15 minutes
I strongly ask and encourage you, please use the Item Data API method if at all possible!
This API method is really ment for adhoc usage, not for bigger automated usage!
{
"count" : 50,
"page" : 1,
"last_page" : 3,
"results" : [
{ /* item #1 - same output as from the item data call */ },
{ /* item #2 */ },
{ /* etc ... */ }
]
}/api/{version}/{format}/recipes/{type}/{page}
* {version} - see the section about Version
* {format} - see the section about Formats
* {type} - either an ID of a discipline or use *all*
* {page} - page offset
Results are cached server side for up to 24 hours
{
"count" : 100,
"page" : 1,
"last_page" : 24,
"results" : [
{ /* recipe #1 - same output as from the recipe data call */ },
{ /* recipe #2 */ },
{ /* recipe #3 */ },
{ /* etc ... */ }
]
}/api/{version}/{format}/recipe/{dataId}
* {version} - see the section about Version
* {format} - see the section about Formats
* {dataId} - the ID of the recipe you want to retrieve data for
Results are cached server side for up to 15 minutes
{
"result" : {
"data_id" : 3473,
"name" : "Fake Recipe",
"result_count" : 3,
"result_item_data_id" : 23654,
"discipline_id" : 1,
"result_item_max_offer_unit_price" : 6523,
"result_item_min_sale_unit_price" : 9345,
"crafting_cost" : 7532,
"rating" : 360,
}
}/api/{version}/{format}/gem-price
* {version} - see the section about Version
* {format} - see the section about Formats
Results are cached server side for up to 15 minutes
Prices are for 100 gold -> x amount of gems
and for 100 gems -> x amount of coin
{
"result" : {
"gem_to_gold" : 3656,
"gold_to_gem" : 23
}
}/api/{version}/{format}/gem-history/{page}
* {version} - see the section about Version
* {format} - see the section about Formats
* {page} - page offset
Results are cached server side for up to 15 minutes
Data is ordered descending by date/time
{
"count" : 100,
"page" : 1,
"last_page" : 33,
"results" : [
{
"datetime" : "YYYY-MM-DD HH:II:SS UTC",
"gem_to_gold" : 3656,
"gold_to_gem" : 23
},
{ /* gem price #2 */ },
{ /* gem price #3 */ },
{ /* etc ... */ }
]
}