Launching /v2/commerce/transactions

Launching /v2/commerce/transactions

in API Development

Posted by: Lawton Campbell

Lawton Campbell

Web Programmer

Next

We’ve just turned on our second authenticated endpoint! It allows players to delegate access to their current and historical Black Lion Trading Post transactions (basically everything that’s shown in the “My Transactions” tab of the in-game Trading Post). There’s more details available in the CDI thread, but for posterity I’ll post some example request/responses.

It’s important to note that all URLs provided by this endpoint require an API key with the “tradingpost” permission.

The first two levels of the URL basically just point to what’s available on lower levels (for self-discovery purposes):

    GET /v2/commerce/transactions HTTP/1.1
    Authorization: Bearer insert-token-here

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
      "current",
      "history"
    ]

Both “current” and “history” endpoints provide separate lists for “buys” and “sells” — due to technical constraints it’s infeasible for us to collate them meaningfully.

    GET /v2/commerce/transactions/current HTTP/1.1
    Authorization: Bearer insert-token-here

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
      "buys",
      "sells"
    ]

Finally, the meat of the endpoint is a paginated list of the last 90 days of transactions (unfortunately, older transactions aren’t available). In the response headers there’s data about the total result set, as well as an RFC5988 Link header. As usual, pagination is controlled via the page and page_size URL parameters.

    GET /v2/commerce/transactions/history/buys?page_size=2 HTTP/1.1
    Authorization: Bearer insert-token-here

    HTTP/1.1 200 OK
    Content-Type: application/json
    X-Page-Size: 2
    X-Page-Total: 143
    X-Result-Count: 2
    X-Result-Total: 286
    Link: , </v2/commerce/transactions/history/sells?page=0&page_size=2>; rel=self, </v2/commerce/transactions/history/sells?page=0&page_size=2>; rel=first, </v2/commerce/transactions/history/sells?page=142&page_size=2>; rel=last

    [
      {
        "id": 2757359846,
        "item_id": 44971,
        "price": 19998,
        "quantity": 1,
        "created": "2015-05-12T06:36:12+00:00",
        "purchased": "2015-05-12T16:55:14+00:00"
      },
      {
        "id": 2756695824,
        "item_id": 24713,
        "price": 425,
        "quantity": 1,
        "created": "2015-05-12T06:35:33+00:00",
        "purchased": "2015-05-12T08:36:50+00:00"
      }
    ]

In the actual body, it’s important to note that the id field does not necessarily correspond when an order is filled (and thus moves from “current” to “history”). This is mostly because for e.g. a sale of 50, there may be multiple buy orders at different dates.

Another constraint to be aware of is that cancelled orders are basically removed from the list. There’s not a clean way right now to discern between a cancelled and filled order, but since only commodities can be traded, it likely isn’t a huge deal.

Finally, the “purchased” field is omitted for the “current” endpoint, since those orders haven’t yet been filled.

Anyway, if you’ve got any questions/concerns post ‘em here and I’ll do my best to address ’em.

EDIT: Also, there’s a 5 minute cache on responses, so you don’t need to poll it that often.

(edited by Lawton Campbell.8517)

Launching /v2/commerce/transactions

in API Development

Posted by: Tiscan.8345

Tiscan.8345

Edit: Looks like the TP is bugged at the moment (2015-05-13, 11:00 GMT) and its not a problem with my code.


I’ve got some problems accessing some endpoints… if i use https://api.guildwars2.com/v2/commerce/transactions or https://api.guildwars2.com/v2/commerce/transactions/current I get the same results as shown in your posting.

But using https://api.guildwars2.com/v2/commerce/transactions/history/buys?page_size=2 or https://api.guildwars2.com/v2/commerce/transactions/history/buys (or anything else i tried) returns either a 502-HTML Error-Page or a JSON-Object stating “ErrTimeout”.

My very simple PHP-Code:

$token = ‘INSERT TOKEN!!!’;

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,“https://api.guildwars2.com/v2/commerce/transactions/history/buys?page_size=2”);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$headers = array();
$headers[] = ’Authorization: Bearer ’.$token;

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$server_output = curl_exec ($ch);

curl_close ($ch);

if (is_json($server_output)) {
print_r(json_decode($server_output));
} else {
var_dump($server_output);
}

function is_json($str){
return json_decode($str) != null;
}

Did I mess up or is there a problem with the API?

(edited by Tiscan.8345)

Launching /v2/commerce/transactions

in API Development

Posted by: AllIsVain.6409

AllIsVain.6409

EDIT: Also, there’s a 5 minute cache on responses, so you don’t need to poll it that often.

Will this be getting reduced in the future, or is this a “take as given” limitation on the API (30 seconds was more what I was hoping for)

Lootballs – Elementalist

Launching /v2/commerce/transactions

in API Development

Posted by: smiley.1438

smiley.1438

I’ve got some problems accessing some endpoints…
[…]

You need to pass along a few more options to curl to make it work with SSL:


curl_setopt_array($ch, [
	CURLOPT_URL            => $url,
	CURLOPT_SSL_VERIFYPEER => true,
	CURLOPT_SSL_VERIFYHOST => 2,
	CURLOPT_CAINFO         => '/path/to/cacert.pem', // download from: http://curl.haxx.se/ca/cacert.pem
	CURLOPT_RETURNTRANSFER => true,
]);

Launching /v2/commerce/transactions

in API Development

Posted by: Tiscan.8345

Tiscan.8345

If SSL was the problem, none of the requests would work (and I can access everything else just fine – and even if I add the SSL-stuff, i still get the same errors).

But it looks like the Trading Post is bugged right now… according to the german and english bug-forums, people can’t access it.

Launching /v2/commerce/transactions

in API Development

Posted by: AllIsVain.6409

AllIsVain.6409

If SSL was the problem, none of the requests would work (and I can access everything else just fine – and even if I add the SSL-stuff, i still get the same errors).

But it looks like the Trading Post is bugged right now… according to the german and english bug-forums, people can’t access it.

It’s currently down as far as I can tell. I had it working using similar code to what you had (adapted for my needs).

Lootballs – Elementalist

Launching /v2/commerce/transactions

in API Development

Posted by: Lawton Campbell

Previous

Lawton Campbell

Web Programmer

Next

Did I mess up or is there a problem with the API?

Yeah there were some unrelated server issues last night; let me know if you’re still experiencing problems.

EDIT: Also, there’s a 5 minute cache on responses, so you don’t need to poll it that often.

Will this be getting reduced in the future, or is this a “take as given” limitation on the API (30 seconds was more what I was hoping for)

5 minutes is our current default; I couldn’t immediately think of any use-cases that would benefit from a reduced TTL so I just left it as default. What did you have in mind?

Launching /v2/commerce/transactions

in API Development

Posted by: AfterXII.2761

AfterXII.2761

Slightly unrelated question, do we know the max character limit on API Keys? (Building a database for accounts and need to know for optimizations)

http://gw2shinies.com/ – A Guild Wars 2 Trading Post Service
http://gw2tno.com/ – The Nameless Ones [TNO]

Launching /v2/commerce/transactions

in API Development

Posted by: Nabrok.9023

Nabrok.9023

Slightly unrelated question, do we know the max character limit on API Keys? (Building a database for accounts and need to know for optimizations)

It’s two GUIDs back-to-back, so char(72) will cover it.

You could get fancy and store it in binary if you really want to. I think this would only require 32 bytes, but you have to write code to handle transferring it back and forth.

“I’m not a PvE, WvW, or PvP player – I am a Guild Wars 2 player”
Tarnished Coast – Dissentient [DIS]
All classes

Launching /v2/commerce/transactions

in API Development

Posted by: AllIsVain.6409

AllIsVain.6409

EDIT: Also, there’s a 5 minute cache on responses, so you don’t need to poll it that often.

Will this be getting reduced in the future, or is this a “take as given” limitation on the API (30 seconds was more what I was hoping for)

5 minutes is our current default; I couldn’t immediately think of any use-cases that would benefit from a reduced TTL so I just left it as default. What did you have in mind?

I was thinking of writing an application that got your recently bought items, extracted the price you bought them for and then gave your a price that would be optimal for resale (a peak price) based on factors. I was planning on integrating this into an overlay, so when you bought an item it ‘immediately’ flashed up showing the best price for flipping. There is no adverse affect for the cache being 5 minutes, it would just make it less streamlined.

Lootballs – Elementalist

Launching /v2/commerce/transactions

in API Development

Posted by: Arridath.1087

Arridath.1087

EDIT: Also, there’s a 5 minute cache on responses, so you don’t need to poll it that often.

Will this be getting reduced in the future, or is this a “take as given” limitation on the API (30 seconds was more what I was hoping for)

5 minutes is our current default; I couldn’t immediately think of any use-cases that would benefit from a reduced TTL so I just left it as default. What did you have in mind?

I can think of a few scenarios where immediate access would be useful. I can’t really think of a use that wouldn’t be restricted by a 5 minute cache.

Launching /v2/commerce/transactions

in API Development

Posted by: Wizeon.3852

Wizeon.3852

I have a problem using this with jQuery ajax requests. The problem is that there is no
Access-Control-Allow-Headers reported by the server, so the preflight request (method OPTIONS) aborts the whole thing. Or is there another way to add the authorization header to the request that wouldn’t trigger the preflight?

And I’d also like the cache to be reduced from 5 minutes, on this endpoint and prices. I can’t track listing changes reliably with a 5 minute cache, no way to get any idea about the velocity of items if you only get a snapshot every 5 minutes. It was great with the old api when you could do pretty much what you can do in-game, refresh the listings every other second and see what orders get filled and how fast.

For this specific case I’d like to alert the user whether their listing is still the top one, or if the listing was fulfilled without the user camping their TP screen. Even a 1 minute would be more useful than the current 5 minute one.

edit: Temporarily solved the ajax problem by not using headers but get parameters which is obviously not the ideal way to go, but at least it works. And the 5 minute timer pretty much makes the tool un-usable, if I put a buy order up it might take 5 minutes for it to show up, and then when it’s filled it might again take 5 minutes for the program to realise it’s been filled. Current version at http://mayumi.fi/gw2tp/

Oh, and to get both buy and sell orders do I have to make two requests, to /buys and to /sells or is there a combined endpoint somewhere?

(edited by Wizeon.3852)

Launching /v2/commerce/transactions

in API Development

Posted by: Lawton Campbell

Previous

Lawton Campbell

Web Programmer

Next

I have a problem using this with jQuery ajax requests. The problem is that there is no
Access-Control-Allow-Headers reported by the server, so the preflight request (method OPTIONS) aborts the whole thing. Or is there another way to add the authorization header to the request that wouldn’t trigger the preflight?

Ah, I forgot to put it in the notes again. You can pass the API key via the ?access_token parameter instead of the Authorization header. By doing that you’ll have a simple request which won’t trigger the preflight (which we don’t support).

And I’d also like the cache to be reduced from 5 minutes, on this endpoint and prices. I can’t track listing changes reliably with a 5 minute cache, no way to get any idea about the velocity of items if you only get a snapshot every 5 minutes.

The /v2/commerce/listings endpoint currently has a 1-second cache. It’s the only one currently that enjoys a non-5-minute cache.

Oh, and to get both buy and sell orders do I have to make two requests, to /buys and to /sells or is there a combined endpoint somewhere?

It’d have to be two requests; I really wanted it to have it the other way but there were some interesting technical constraints.

Launching /v2/commerce/transactions

in API Development

Posted by: Wizeon.3852

Wizeon.3852

Thanks! In the end the get parameter is the only way to go then if I don’t want to send the user API key to my backend first which could handle the authorisation headers without preflight.

I posted about the 1 second cache on the fair-use thread since it doesn’t actually seem to be a 1 second cache.

Is there any chance to drop the cache timer on the transactions endpoint to a more reasonable one? Even 1 minute or the previously requested 30 seconds would be so much more useful in tracking your current orders “live” from outside the game.

Launching /v2/commerce/transactions

in API Development

Posted by: Lawton Campbell

Previous

Lawton Campbell

Web Programmer

Next

The cache time on /v2/commerce/transactions is going to drop to 1min; just pushed out the config change, it should take effect within the hour.

Ultimately, polling HTTP isn’t a good medium for these use-cases. I mostly intended the endpoint to be used for offline purposes — e.g., export and data analysis. For a real-time dataflow it would be better for all parties if we used a protocol to push data down to the consumer. Unfortunately, our backend isn’t currently designed to support such an access pattern, so I’m not sure if we’ll ever be able to satisfy that use-case.

Not saying that it’ll never happen, just that there’s a lot of work to be done to support real-time notifications e.g., HTTP long polling or websockets or server-sent events or what have you.

Launching /v2/commerce/transactions

in API Development

Posted by: rodadams.5963

rodadams.5963

I’ll point out that we can overcome not having backend support for this. You could build a single internal scanner, which would poll the backend with as fast an update speed as you can, and then when you notice a change, push that out.

It’s not a perfect solution, but it’s an option.

Launching /v2/commerce/transactions

in API Development

Posted by: Wizeon.3852

Wizeon.3852

I don’t think your API is obeying the config values, but is using some global 5min cache regardless of what’s in the config.

/v2/commerce/transactions still has a 5min delay if I change an order as soon as I see the last change occur, and /v2/commerce/listings is supposed to have 1sec cache but it’s 5min as well.

Launching /v2/commerce/transactions

in API Development

Posted by: Lawton Campbell

Previous

Lawton Campbell

Web Programmer

Next

I don’t think your API is obeying the config values, but is using some global 5min cache regardless of what’s in the config.

Yeah, I have a feeling that bit is broken. It’s one of the few bits that I don’t have unit tests for. I’ll try to get that fixed.

Launching /v2/commerce/transactions

in API Development

Posted by: Pat Cavit.9234

Previous

Pat Cavit.9234

Web Programming Lead

Next

Found & fixed the cache bug on dev, will try to get it deployed next week.

Launching /v2/commerce/transactions

in API Development

Posted by: Wizeon.3852

Wizeon.3852

Thanks a lot! Nice to know that devs are listening

Launching /v2/commerce/transactions

in API Development

Posted by: cephiroth.6182

cephiroth.6182

One question regarding pagination:
The situation I am thinking of is that the client is iterating over the pages while the data changes. Is this covered by the server in any way (e.g. producing a snapshot on loading page 0) or does the client have to deal with incomplete or duplicate result sets?

Launching /v2/commerce/transactions

in API Development

Posted by: Lawton Campbell

Previous

Lawton Campbell

Web Programmer

You should probably handle incomplete/duplicate result sets if you care about fidelity.

Most of the unauthenticated endpoints don’t change their data until a patch lands though, so it’s not really that big of a deal. The only place it’ll really bite you (maybe) is the transactions endpoint.

Launching /v2/commerce/transactions

in API Development

Posted by: Risingashes.8694

Risingashes.8694

Would it be possible to expose items waiting in a character’s Delivery Box?

This would be very helpful information personally.

Launching /v2/commerce/transactions

in API Development

Posted by: Devilsown.9376

Devilsown.9376

Only 50 trades are shown over /transactions/current/sells

Arround June, I thought it’s only for the first time, for testing the Api, so I didn’t ask, but in between I think I should:
Is that intentional or is it a mistake?

Launching /v2/commerce/transactions

in API Development

Posted by: Eearslya.6309

Eearslya.6309

You’re hitting the default page limit. Use the ?page and ?page_size request variables (max size of 200 per page) to get more results.

Blackgate
Harbinger Tryssa – Revenant

Launching /v2/commerce/transactions

in API Development

Posted by: Devilsown.9376

Devilsown.9376

Ups, I’d forgotten that thing with page.
Thank you for the hint.