API v0.9

philipw1 edited this page Feb 10, 2014 · 45 revisions
Clone this wiki locally

API v0.9

Mailing List

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!

Errors

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!!

Paging

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 ;-)

Fair Use Policy

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 ;)

Date and Time

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!

Prices

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!

"result" or "results"

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

Version

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.

Arguments vs Parameters

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.

Formats

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!

JSONP

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).

Examples & Guides

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

API Methods

Type List

Arguments

/api/{version}/{format}/types
* {version} - see the section about Version
* {format}  - see the section about Formats

Notes

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 ;)

Response

{
"results" : [
    {
        "id"       : 0,
        "name"     : "Armor",
        "subtypes" : [
            {
                "id"       : 0,
                "name"     : "Coat",
            },
            {
                "id"       : 1,
                "name"     : "Gloves",
            }
            { /* subtype #3 */ },
            { /* etc ... */ }
        ]
    },
    { /* type #2 */ },
    { /* type #3 */ },
    { /* etc ... */ }
]
}

Discipline List

Arguments

/api/{version}/{format}/disciplines
* {version} - see the section about Version
* {format}  - see the section about Formats

Notes

Results are cached server side for up to 24 hours

Response

{
"results" : [
    {
        "id"       : 1,
        "name"     : "Armorsmith",
    },
    { /* discipline #2 */ },
    { /* discipline #3 */ },
    { /* etc ... */ }
]
}

Rarity List

Arguments

/api/{version}/{format}/rarities
* {version} - see the section about Version
* {format}  - see the section about Formats

Notes

Results are cached server side for up to 24 hours

Response

{
"results" : [
    {
        "id"       : 1,
        "name"     : "Common",
    },
    {
        "id"       : 1,
        "name"     : "Fine",
    },
    { /* rarity #3 */ },
    { /* rarity #4 */ },
    { /* etc ... */ }
]
}

Full Item List

Arguments

/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*

Notes

Results are cached server side for up to 3 minutes

Response

{
"count"     : 100,
"results"   : [
    { /* item #1 - same output as from the item data call */ },
    { /* item #2 */ },
    { /* item #3 */ },
    { /* etc ... */ }
]
}

Item List

Arguments

/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

Parameters

?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!  

Notes

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 ;)

Response

{
"count"     : 100,
"page"      : 1,
"last_page" : 24,
"results"   : [
    { /* item #1 - same output as from the item data call */ },
    { /* item #2 */ },
    { /* item #3 */ },
    { /* etc ... */ }
]
}

Item Data

Arguments

/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

Notes

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!).

Response

{
"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 ;)
}
}

Item Listings

Arguments

/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

Notes

Results are cached server side for up to 15 minutes
Data is ordered descending by date/time

Response

{
"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 ... */ }
]
}

Item Search

Arguments

/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

Notes

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!

Response

{
"count"     : 50,
"page"      : 1,
"last_page" : 3,
"results"     : [
    { /* item #1 - same output as from the item data call */ },
    { /* item #2 */ },
    { /* etc ... */ }
]
}

Recipe List

Arguments

/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

Notes

Results are cached server side for up to 24 hours

Response

{
"count"     : 100,
"page"      : 1,
"last_page" : 24,
"results"   : [
    { /* recipe #1 - same output as from the recipe data call */ },
    { /* recipe #2 */ },
    { /* recipe #3 */ },
    { /* etc ... */ }
]
}

Recipe Data

Arguments

/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

Notes

Results are cached server side for up to 15 minutes

Response

{
"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,
}
}

Current Gem Price

Arguments

/api/{version}/{format}/gem-price
* {version}     - see the section about Version
* {format}      - see the section about Formats

Notes

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

Response

{
"result" : {
    "gem_to_gold" : 3656,
    "gold_to_gem" : 23
}
}

Gem Price History

NOT IMPLEMENTED YET

Arguments

/api/{version}/{format}/gem-history/{page}
* {version}     - see the section about Version
* {format}      - see the section about Formats
* {page}        - page offset

Notes

Results are cached server side for up to 15 minutes
Data is ordered descending by date/time

Response

{
"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 ... */ }
]
}