[API Suggestion] World vs World

[API Suggestion] World vs World

in API Development

Posted by: Felix Omni.3829

Felix Omni.3829

In keeping with Cliff’s request here, this is a thread for suggestions and requests for the World vs World API, which includes:

https://api.guildwars2.com/v1/wvw/matches.json

https://api.guildwars2.com/v1/wvw/match_details.json

https://api.guildwars2.com/v1/wvw/objective_names.json

I think the number one suggestion/request in this category (at least as far as I’m concerned) is that the API needs to provide more information on objectives, in particular the actual objective name instead of just “Tower” and the point value and/or “type” of the objective. Right now these things have to be hardcoded, and that’s pretty lousy. (Though thanks to the people in this thread, we at least have an accurate list for the time being.)

Another request I’ve seen is giving us the current point value “incomes” of each team alongside the total scores. If we get the point values of each objective this will be less necessary, but it would still be convenient.

That’s all I’ve got; please add to the thread with your suggestions and requests.

(edited by Felix Omni.3829)

[API Suggestion] World vs World

in API Development

Posted by: Sorrow.7384

Sorrow.7384

Thanks for putting my suggestion in there, Felix.

They could go a step further and calculate the number of towers/keeps/camps/castles held for each server as well. Basically mimicking the data in the score screen.

Something like


"objectives_overview":[{"towers":8,"keeps":2,"camps":12,"castle":0}]

I know we could do this ourselves once we get a good objective_names.json file but it could save developers a ton of time who just want to show the overview rather than having to calculate all that data.

Getting a guild_names.json file would be helpful as well.

[API Suggestion] World vs World

in API Development

Posted by: smiley.1438

smiley.1438

once we get a good objective_names.json file

I know, it’s not official, but it’s all you need – i believe, objectives are the least thing which will change

https://gist.github.com/codemasher/bac2b4f87e7af128087e

[API Suggestion] World vs World

in API Development

Posted by: Drakma.1549

Drakma.1549

Seems rather needless if you ask me. You can easily get this information.

I’ve been doing it since day 1 of the API in gw2stats.net

[API Suggestion] World vs World

in API Development

Posted by: Felix Omni.3829

Felix Omni.3829

Seems rather needless if you ask me. You can easily get this information.

I’ve been doing it since day 1 of the API in gw2stats.net

The information is available but not through the API, that’s the problem. Unless you’re saying otherwise?

[API Suggestion] World vs World

in API Development

Posted by: Tanis.5134

Tanis.5134

Type consistency. I know it was acknowledged <a href="https://forum-en.gw2archive.eu/forum/community/api/Nit-Type-inconsistency">here</a>, but the string vs int world names are obnoxious to work with.

Either an API mapping WvW objectives to objective types, or standardize the “camp” type into one. The dozen or so different names for “camp” make for extra work for us, and I don’t think they are all that useful. I’m sure there’s a use for it, but…

[API Suggestion] World vs World

in API Development

Posted by: Atrophied.8725

Atrophied.8725

Upgrade status on objectives would be awesome. Just the readily visible ones: wall, door and waypoint upgrades. Nothing that you can’t see from the map or from running by.

Xandra – 80s in all classes – Ele/Guard mains – [TL] – NSP

[API Suggestion] World vs World

in API Development

Posted by: Cruzyo.7304

Cruzyo.7304

Upgrade status on objectives would be awesome. Just the readily visible ones: wall, door and waypoint upgrades. Nothing that you can’t see from the map or from running by.

to be honest, if you know how the supply cap of a fortification works, you can call what upgrades are on just from running by.

[API Suggestion] World vs World

in API Development

Posted by: kaspi.7164

kaspi.7164

Upgrade status on objectives would be awesome. Just the readily visible ones: wall, door and waypoint upgrades. Nothing that you can’t see from the map or from running by.

You can’t see the upgrade status from the map on enemy objectives except for the waypoint. Which is why the API probably won’t include that information. It’s what Anet is having their eyes on and what they mentioned on multiple occasions – they don’t want the API to provide an unfair advantage.

“If you want to see the upgrades on towers or where enemies have arrow carts, go code it yourself” is imo basically what they’re saying.

Even the new MOS feature with Righteous Indignation is pushing it and it’s a simple diff between two status changes for an objective. Accuracy depends on how frequently you call the API to get updates, but 5-10 seconds would be precise enough.

[SWD] Tal Emenar
EU-Piken Square

[API Suggestion] World vs World

in API Development

Posted by: TatsuKan.5412

TatsuKan.5412

I created a small json file that can be used to calculate the income.
Each objective has its English name and its income value.

http://tatsu-kan.com/gw2/objective_income.json

[CPC] [Vizunah Square] – Nantes (http://en.wikipedia.org/wiki/Nantes)

[API Suggestion] World vs World

in API Development

Posted by: Cruzyo.7304

Cruzyo.7304

Upgrade status on objectives would be awesome. Just the readily visible ones: wall, door and waypoint upgrades. Nothing that you can’t see from the map or from running by.

You can’t see the upgrade status from the map on enemy objectives except for the waypoint. Which is why the API probably won’t include that information. It’s what Anet is having their eyes on and what they mentioned on multiple occasions – they don’t want the API to provide an unfair advantage.

Even tough its true you cant get that information from the map.
A scout that is passing these objectives will surely be able to tell you very accurate what upgrades a keep has finished.

Beside the obvious structural ones (walls/gates, oil, canons, mortar, waypoint) also the personnel ones.

This comes simply by observating the Supply Cap in the keep.
a fully upgraded keep holds 1700 supplies. a nonupgraded keep holds 500.

Each Tier 1 Upgrade adds 50 to this cap
Each Tier 2 Upgrade adds 100 to this cap
Each Tier 3 Upgrade adds 150 to this cap.

If you have a fully structural upgraded keep it holds 1100 supplies max.
Adding services or a second worker to it will increase it to 1150 – this is the only thing you wont be able to call for a 100% if the keep is at 1150 supplies. beyond that it’s possible again.

1200 will mean both tier 1 personell.

1250 will mean 1 tier 1 and 1 tier 2 upgrade. If its additional guards, you can see by passing a gate and doing a headcount, if you dont see more guards than at an unupgraded keep, this keep owns a merchant and a banker. If you see additional guards, this keep owns a second worker and more guards.

the list goes on, If you know how to this stuff works, you can figure it all out on your own. So i dont see why an API shouldnt be able to provide this information

[API Suggestion] World vs World

in API Development

Posted by: kaspi.7164

kaspi.7164

@Cruzyo: Yes, but you need to log into the game, go to the keep and have a look for yourself. Or you have to send out scouts to tell you. It requires some effort on the player side.

I’ll use an absurd example: The next step would be providing the locations of enemy siege. You can see it too, if you pass by.

I think this particular API is good as it is. Could use improvement on the naming part and the related APIs (guilds). Also the API as a whole could use a “last modified” header…

[SWD] Tal Emenar
EU-Piken Square

[API Suggestion] World vs World

in API Development

Posted by: EnemyCrusher.7324

EnemyCrusher.7324

1. Proper objective names

2. “Contested” boolean for each objective in match details

3. Status of upgrades for each objective in match details

4. Add mercenary camp statuses to match details

5. “Outmanned” list for each map in match details that lists which servers are outmanned on that map (empty list if none)

Light of Honor [Lite] – Founder / Warmaster
Sorrow’s Furnace Commander
“You’re the mount, karka’s ride you instead, and thus they die happy!”-Colin Johanson

(edited by EnemyCrusher.7324)

[API Suggestion] World vs World

in API Development

Posted by: titanlectro.5029

titanlectro.5029

1. Proper objective names

2. “Contested” boolean for each objective in match details

3. Status of upgrades for each objective in match details

4. Add mercenary camp statuses to match details

5. “Outmanned” list for each map in match details that lists which servers are outmanned on that map (empty list if none)

^^^ this

Gate of Madness | Leader – Phoenix Ascendant [ASH]
Niniyl (Ele) | Barah (Eng) | Luthiyn (War) | Niennya (Thf)
This is my Trahearne’s story

[API Suggestion] World vs World

in API Development

Posted by: Tanis.5134

Tanis.5134

Could we get the match start/end time somewhere?
I know that it is currently every Friday at 6:00 PM PDT, but it would be nice to be able to get that data from the API should it change again in the future.

[API Suggestion] World vs World

in API Development

Posted by: smiley.1438

smiley.1438

Just got the idea that the current rank and rating could be handy in the world_names.json.

€:

guessing the scores right score from the scores array in the match_details response is a bit confusing since its in a different order than the maps, why not change it like that:

scores: {
	red: 128115,
	blue: 123980,
	green: 188740
}

The maps array would also look better if it was of object type like:


maps: {
	RedHome:{
		scores: {
			red: 128115,
			blue: 123980,
			green: 188740
		},
		objectives: {
			objective_id: {
				...
			}
		}	
	}
	...
}

(edited by smiley.1438)

[API Suggestion] World vs World

in API Development

Posted by: Snowreap.5174

Snowreap.5174

I was very surprised to find that server rating and volatility are not exposed in the API. instead, I guess we’re supposed to fetch from the leaderboards and parse the html?

-ken

The Purge [PURG] – Ehmry Bay

[API Suggestion] World vs World

in API Development

Posted by: turshija.3627

turshija.3627

It would be great if we had a bool “attacked” true/false for every objective (next to id, owner and owner_guild).
That way we could make an app that refreshes current match and notifies you whenever some objective gets attacked

Searchable leaderboards → http://www.gwshack.info
Leaderboards feedback → /forum/pvp/pvp/Leaderboards-with-search-www-gwshack-info/first

[API Suggestion] World vs World

in API Development

Posted by: Tanis.5134

Tanis.5134

We also currently don’t have a good way of mapping objectives from the API to an actual objective in the world. In other words, the API doesn’t provide a way to say “Objective 29 is a north camp.” I am currently relying on a manually created map from IDs to objectives, which is a pain.

If we could get that data from the API somehow, that would be awesome. Even outputting the objective IDs in a consistent order between borderlands would make interpreting the IDs a whole lot more simple.

[API Suggestion] World vs World

in API Development

Posted by: EnemyCrusher.7324

EnemyCrusher.7324

And appending to my list:

6. Add sentry statuses to match details and add them to objective names (with understandable names)

Light of Honor [Lite] – Founder / Warmaster
Sorrow’s Furnace Commander
“You’re the mount, karka’s ride you instead, and thus they die happy!”-Colin Johanson

[API Suggestion] World vs World

in API Development

Posted by: Snowreap.5174

Snowreap.5174

Ok, I’m making this an “official” suggestion now: please add exact world ratings, deviations and volatilities to the API.

the Leaderboard has values for these, but there are 2 problems with them: (1) you have to parse the HTML to extract them and (2) they are rounded to 4 decimal places. If you try to use rounded values to predict new ratings, you end up with different numbers than ArenaNet publishes, and I’m guessing this is because ArenaNet has exact starting values that are of a higher precision than the Leaderboard shows.

A change in the 5th decimal place of volatility (which we don’t see on the Leaderboard) cascades into a rather large change in predicted deviation (it shows up in the 3rd decimal place), which then cascades into large changes in predicted rating (sometimes large enough to affect predicted ranking).

-ken

The Purge [PURG] – Ehmry Bay

[API Suggestion] World vs World

in API Development

Posted by: Snowreap.5174

Snowreap.5174

I think https://api.guildwars2.com/v1/wvw/match_details.json needs to include timestamps to show the last time ownership changed (or to show when the current ownership took effect).

The reason for this is, many people are relying on the API to detect when an objective changes hands, at which time they start a 5 minute countdown so they’ll know when the objective becomes ‘capturable’ again. in order to get one-second accuracy on the countdown, this means you need to query that API around twice a second. that’s a lot.

People doing this could dramatically reduce their query frequency if the results included a timestamp showing when the ownership change occurred.

-ken

The Purge [PURG] – Ehmry Bay

[API Suggestion] World vs World

in API Development

Posted by: ElGreenGo.6734

ElGreenGo.6734

It would be nice if match_details.json included a timestamp for the last and/or next point accumulation.

I’ve been playing around with detecting it with the following algorithm:

  • Figure out the total points available in the match
  • Save the total combined scores of all three teams
  • Every 30 seconds call match_details.json to get the current score
  • If the current combined score is bigger than the saved score + total points available the previous round has ended

Doing it this way you can fairly accurately detect the end of a scoring round but it requires frequently polling. Once you know when the last one happened you can poll less frequently but it would be nice if we just had a timestamp and could only call match_details.json every 15 minutes if we were only interested in major point changes.

If you had a timestamp for the previous or next round you could figure out the missing timestamp by adding or subtracting 15 minutes BUT it would be useful to have timestamps for both the previous and next round just in case the duration of a round ever changes in the future.


As a side note, I think a good rule of thumb for what should/shouldn’t be visible via the API would be to only expose things that a player could observe by staring at the map. I.e. you can’t see upgrades, siege location, etc. But you could watch for objectives changing hand and manually record when it happened. As ken said, this is already observable via the API, but it currently requires pounding the API servers with frequent requests.

[API Suggestion] World vs World

in API Development

Posted by: mtodor.2356

mtodor.2356

It would be nice to allow multiple Match IDs in match_details.json request. That will reduce number of request – because in most cases all match_ids will be required for one region to generate list.

[API Suggestion] World vs World

in API Development

Posted by: Narax.7605

Narax.7605

Ok, I’m making this an “official” suggestion now: please add exact world ratings, deviations and volatilities to the API.

the Leaderboard has values for these, but there are 2 problems with them: (1) you have to parse the HTML to extract them and (2) they are rounded to 4 decimal places. If you try to use rounded values to predict new ratings, you end up with different numbers than ArenaNet publishes, and I’m guessing this is because ArenaNet has exact starting values that are of a higher precision than the Leaderboard shows.

A change in the 5th decimal place of volatility (which we don’t see on the Leaderboard) cascades into a rather large change in predicted deviation (it shows up in the 3rd decimal place), which then cascades into large changes in predicted rating (sometimes large enough to affect predicted ranking).

-ken

Reading the data from this page " https://leaderboards.guildwars2.com/en/eu/wvw " at least worked in the past but now there are the randomized ratings so now we can only take our calculated ratings from the week before… That’s bad and inaccurate. :/

Elona Reach [DE]
gw2wvw.org

[API Suggestion] World vs World

in API Development

Posted by: Snowreap.5174

Snowreap.5174

I think the ratings posted on the leaderboards are supposed to be the ‘true’ ratings (not the randomized ‘matchup’ ratings), but the problem is too few decimal places in order to accurately calculate expected values for the next week.

But the EU leaderboards show the ratings as of June 3. Why is that? I thought the match started on May 31 / June 1? I think this may be a bug in the leaderboards. For the US, the leaderboards show the May 31 ratings.

-ken

The Purge [PURG] – Ehmry Bay

[API Suggestion] World vs World

in API Development

Posted by: Narax.7605

Narax.7605

No, the EU ratings are definitely wrong. On http://mos.millenium.org/matchups there are the correct ones of the end of last week. Even the matchup is wrong, “Seafarer’s Rest” is in Tier 2, not in Tier 1…
So I don’t want to rely on that page, the API values are correct but without rating, dev and vol.

Elona Reach [DE]
gw2wvw.org

(edited by Narax.7605)

[API Suggestion] World vs World

in API Development

Posted by: Surmaturma.4823

Surmaturma.4823

Is there already an overlay to GW2 window which would give map specific status? That would be absolutely great. So you could on your playing screen see camp CDs etc…

I know that dual-monitor people do not have an issue but us poor 1 monitor ones could really benefit from overlay on GW2 window

“To Rasa Sum – and back again!”

(edited by Surmaturma.4823)

[API Suggestion] World vs World

in API Development

Posted by: SpaceCowboy.1398

SpaceCowboy.1398

I think https://api.guildwars2.com/v1/wvw/match_details.json needs to include timestamps to show the last time ownership changed (or to show when the current ownership took effect).

^ This!

Totally need this. I’m a frontend web dev, so to my understanding the only way to do this current is to purchase a web server that can run a backend script every second and record when changes occur.

So, please please add this!!!

-Cowboy

Darmon, Asura Thief | Darmx, Asura Engineer
[EU] Gandara

[API Suggestion] World vs World

in API Development

Posted by: Daze.6914

Daze.6914

I think https://api.guildwars2.com/v1/wvw/match_details.json needs to include timestamps to show the last time ownership changed (or to show when the current ownership took effect).

^ This!

Totally need this. I’m a frontend web dev, so to my understanding the only way to do this current is to purchase a web server that can run a backend script every second and record when changes occur.

So, please please add this!!!

-Cowboy

That’s how the MOS Millenium website is able to constantly show the various timers.
You can’t do that without a webserver so mobile apps can’t currently show those data when they are initialized.

War Inc. Community [WIC]
Far Shiverpeaks
GW2 WvW - GW2 Gem Price

[API Suggestion] World vs World

in API Development

Posted by: ScArZ.4953

ScArZ.4953

1. Proper objective names

2. “Contested” boolean for each objective in match details

3. Status of upgrades for each objective in match details

4. Add mercenary camp statuses to match details

5. “Outmanned” list for each map in match details that lists which servers are outmanned on that map (empty list if none)

My only request is for number 2 =D

I agree that using the API should not give extra information that is not readable from the map. I had thought to request for things like “Life % of Gate/Wall” but realise that it would give too much advantages. Because some strategies includes sending a fake attack to a objective across the map so as to divert attention. Knowing if the “Life % of Gate/Wall” is not going down will effectively void such a strategy.

We also currently don’t have a good way of mapping objectives from the API to an actual objective in the world. In other words, the API doesn’t provide a way to say “Objective 29 is a north camp.” I am currently relying on a manually created map from IDs to objectives, which is a pain.

If we could get that data from the API somehow, that would be awesome. Even outputting the objective IDs in a consistent order between borderlands would make interpreting the IDs a whole lot more simple.

Couldn’t you make it a data file or something and just reference to it in your codes? You could use things like Enum, classes or well even static variables. I also found some sources that have converted the IDs to Names as a JSON format which you could use but I personally just hardcoded it somewhere.

Although this becomes a possible problem if the API IDs to Names mapping changes in the future

(edited by ScArZ.4953)

[API Suggestion] World vs World

in API Development

Posted by: Tanis.5134

Tanis.5134

Couldn’t you make it a data file or something and just reference to it in your codes? You could use things like Enum, classes or well even static variables. I also found some sources that have converted the IDs to Names as a JSON format which you could use but I personally just hardcoded it somewhere.

Although this becomes a possible problem if the API IDs to Names mapping changes in the future

That’s exactly what I’m doing, and you pointed out why I don’t like doing it. I would like my app to be as future-proof as possible.

I also don’t personally feel as though a client application SHOULD need to map IDs to specific objectives. That sounds like something you would typically get from an API, not make up yourself.

[API Suggestion] World vs World

in API Development

Posted by: Nabrok.9023

Nabrok.9023

I think https://api.guildwars2.com/v1/wvw/match_details.json needs to include timestamps to show the last time ownership changed (or to show when the current ownership took effect).

The reason for this is, many people are relying on the API to detect when an objective changes hands, at which time they start a 5 minute countdown so they’ll know when the objective becomes ‘capturable’ again. in order to get one-second accuracy on the countdown, this means you need to query that API around twice a second. that’s a lot.

People doing this could dramatically reduce their query frequency if the results included a timestamp showing when the ownership change occurred.

-ken

That’s crazy, you don’t need that level of accuracy.

Does it really matter if you get to the camp a few seconds after the buff expires? Even if you answered yes to that, you couldn’t really do it anyway as the API can sometimes take a few seconds to respond.

I don’t see any reason to pull match_details more than about every 5 seconds.

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

[API Suggestion] World vs World

in API Development

Posted by: Snowreap.5174

Snowreap.5174

and yet, if ArenaNet looks at their API traffic I’m sure they’ll see that people are querying that often anyway.

if the API included timestamps you could get away with querying once a minute (or less), if all you wanted to know is when something becomes capturable again.

in that case, the only reason to query more frequently would be to more rapidly report the fact that the objective has been flipped (because knowing that it has just flipped can often give you a good idea of where your enemies are right this instant — knowing where they were 20 seconds or a minute ago is usually a lot less useful).

arguably, if people are going to query that frequently anyway, then making the responses bigger to report more accurate countdowns would do nothing except increase API traffic. but it seems reasonable to suppose that there are people out there who would query less frequently if the API included timestamps, so why not let them do so?

-ken

The Purge [PURG] – Ehmry Bay

[API Suggestion] World vs World

in API Development

Posted by: Torasan.6029

Torasan.6029

I’ve started commanding recently and I must say its an extremely challenging role to play. Theres a huge expectation to know all and yet maintain a fast pace and fight hard. I lead from the front; first in, last out. At the same time I’m expected to know where we need to go next etc…

I’ve been using an excellent program called Wuverlay to help me make decisions when commanding. It uses your API data to update a pie chart representation of the map which enables users to clearly identify when locations have been captured and if locations have the immunity buff.

I’m posting to request that you add ‘contested’ data to the API so that commanders and others using Wuverlay or other map alternatives can see this vital information.

Using the in game map for this is slow and cumbersome. The Minimap needs to be relatively zoomed in to aid combat and its a pain to pull up and zoom out of the full map regularly.

[API Suggestion] World vs World

in API Development

Posted by: smiley.1438

smiley.1438

Now that we have a maps API, the coordinates for WvW objectives would be greatly appreciated. (beside the correct objective names and types)

https://api.guildwars2.com/v1/wvw/objective_names.json

[API Suggestion] World vs World

in API Development

Posted by: Nabrok.9023

Nabrok.9023

Now that we have a maps API, the coordinates for WvW objectives would be greatly appreciated. (beside the correct objective names and types)

https://api.guildwars2.com/v1/wvw/objective_names.json

Yeah, I figured them out by changing the example script to use the WvW map and clicking on each of the locations (which outputs the co-ordinates to the javascript console). But, it would be nice to have this so that I could just import them, especially if there are any changes/additions in the future.

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

[API Suggestion] World vs World

in API Development

Posted by: smiley.1438

smiley.1438

Hehe, thats the why i did it with my gmaps powerd wvw map weeks ago
https://chillerlan.net/gw2/wvw.html

[API Suggestion] World vs World

in API Development

Posted by: quenoz.3859

quenoz.3859

Now that we have a maps API, the coordinates for WvW objectives would be greatly appreciated. (beside the correct objective names and types)

https://api.guildwars2.com/v1/wvw/objective_names.json

i agree, hoping that this will be in very soon

The Unlikely Plan [TUP] Raid Leader

[API Suggestion] World vs World

in API Development

Posted by: smiley.1438

smiley.1438

I’ve updated the JSON in my gist with the (approx) coordinates of the objectives. I’ve also changed the JSON structure a bit to how i’d like to see the response of the objective_names API.

https://gist.github.com/codemasher/bac2b4f87e7af128087e

{
	"Center": [
		{
			"id": 1,
			"score": 25,
			"coords": [10766, 13656],
			"type": "keep",
			"name": {
				"de": "Aussichtspunkt",
				"en": "Overlook",
				"es": "Mirador",
				"fr": "Belvédère"
			}
		}
	],
	"BlueHome": [
		...
	],
	"GreenHome": [
		...
	],
	"RedHome": [
		...
	]
}


id is the objective_id obviously – this could be also used as identifier (which is passed to e.g. jQuery’s $.each()), score and type are somehow redundant, so one of them could be dropped.

{
	"Center": {
		"1": {
			"score": 25,
			"coords": [10766, 13656],
			"name": {
				"de": "Aussichtspunkt",
				"en": "Overlook",
				"es": "Mirador",
				"fr": "Belvédère"
			}
		}
	},
	...
}

(edited by smiley.1438)

[API Suggestion] World vs World

in API Development

Posted by: Ice of Dragons.1637

Ice of Dragons.1637

There should be an extension to the current WvW api,
that shows current leader board standings, past matches,
current and upcoming matches.

[API Suggestion] World vs World

in API Development

Posted by: smiley.1438

smiley.1438

I’ve just had an idea for a more convinient matches.json, shrinked down to ~1/4 of the size of the current response:
https://gist.github.com/codemasher/8876102

opinions?

[API Suggestion] World vs World

in API Development

Posted by: blackoil.2673

blackoil.2673

I’ve just had an idea for a more convinient matches.json, shrinked down to ~1/4 of the size of the current response:
https://gist.github.com/codemasher/8876102

opinions?

I really don’t use the API but I know about API design.
This looks good, because the size gets really smaller, but it’s not as self-explanatory as the current.

What I mean is that I first looked into your idea and there were parts that I didn’t understand:
-> What’s start and end?
-> Why EU and NA “objects” have indexed values (“1”: {}, “2”:{}, “3”:{}, …) instead of making them an array?
-> If i didn’t know about WvW matches (which I do), what does b, g, r mean? (yea, I knew it’s blue green red, but I really wouldn’t know)

Then I looked at the current version and I could understand everything:
-> Each match “object” has start_time and end_time, with a human-readible date format (And then I found out you put it as UNIX timestamp, that’s great for computers)
-> Each match object has it’s match id, composed by 2 numbers. I suppose the ones that start by 1 is one region and the ones that start by 2 is the other, and then they’re numbered. But you really can’t split this thing, as it’s an id. You really shouldn’t care about what does it mean
-> Each map has it’s name (red world, blue world and green world)

In conclusion:
-> I like the UNIX timestamp. APIs are for computers, not for humans
-> It’s also great that it takes less bandwith
-> But at the cost of making the json not self-explanatory. I really would make some hybrid that anyone can still understand but takes less bandwith than the current one. Else why don’t you just pass binary data instead of json?
-> I wouldn’t split the id’s. I would do {"EU":{"1-1":{…},1-2,“NA”:{"2-1":{…},2-2. (or changing 1 by 2, idk which is eu and na…) Id’s can’t be splitted. They identify something. [Actually, the id’s should be “EU-1”..“EU-N” and “NA-1”…“NA-N” but… that could be hard to change]

What I mean is that APIs are made for computers, so it should be fast for a computer to process the data. But it also has to be understandable for a developer.

(edited by blackoil.2673)

[API Suggestion] World vs World

in API Development

Posted by: smiley.1438

smiley.1438

Hey, thanks for your feedback! In the following i’ll explain some points why i did certain things:

→ What’s start and end?

→ Each match “object” has start_time and end_time, with a human-readible date format (And then I found out you put it as UNIX timestamp, that’s great for computers)

Ok, i must admit i could have named these startTime and endTime. Since these are (currently) the same for all matches per region, it’s completely useless to add them for each match item – ~1000 bytes of useless overhead – also due to the suboptimal time format which you would parse to a timestamp or a better human readable format in most cases anyway.

→ Why EU and NA “objects” have indexed values (“1”: {}, “2”:{}, “3”:{}, …) instead of making them an array?

→ Each match object has it’s match id, composed by 2 numbers. I suppose the ones that start by 1 is one region and the ones that start by 2 is the other, and then they’re numbered. But you really can’t split this thing, as it’s an id. You really shouldn’t care about what does it mean

→ I wouldn’t split the id’s. I would do {"EU":{"1-1":{…},1-2,“NA”:{"2-1":{…},2-2. (or changing 1 by 2, idk which is eu and na…) Id’s can’t be splitted. They identify something. [Actually, the id’s should be “EU-1”..“EU-N” and “NA-1”…“NA-N” but… that could be hard to change]

The match_id isn’t actually an ID but 2 IDs, joined by a hyphen: the region and the matchup tier. I still wonder why Anet chose this format instead of having 2 parameters for the match_details.json like region and tier, both optional so that you could retrieve the match_details for all, a region or a single match if you like. That way it would make the life for database maintainers like millenium.org way easier since you wouldn’t need to loop through the matches.json and call the API 17 times to get the data for all matches.
As soon as i saved the gist yesterday, i realized that it would be much better to have the region IDs instead of “EU” and “NA” as identifiers. You may have noticed that it’s currently impossible to access the data for a single matchup or the start and end times for a specific region directly: you have to loop through the whole thing, and check for the match_id since the response is completely unordered. (i have already updated the gist added a regions object which holds the region IDs with the corresponding region to make it a little more descriptive)

So if you had a JSON like mine, you would just do this:

var matchData = {...} // the JSON response

var match = matchData.matches[2][3]; // data for match id 2-3 which is the EU tier 3 matchup

If you still need to loop through the whole thing (or lets say through all matches in a region) you could do this:

var regionID = 1; // your region id of choice, from a config or wherever you want

// prototype.js
// http://api.prototypejs.org/language/Hash/prototype/each/
$H(matchData.matches[regionID]).each(function(match){
	console.log(regionID+'-'+match.key); // match id
	console.log(match.value); // match worlds

	//yada yada yada...
});

In PHP it could be something like this:

$json = '{...}'; // get it e.g. via file_get_contents()

// the second parameter for json_decode makes it an associative array 
// i prefer these over objects because of the more handy syntax
$matchdata = json_decode($json, true); 

$match = $matchdata['matches'][2][3]; // EU tier 3 matchup

$regionID = 1;

foreach($matchdata['matches'][$regionID] as $tier => $worlds){
	echo $regionID.'-'.$tier;
	print_r($worlds);
	
	// ...
}

[API Suggestion] World vs World

in API Development

Posted by: smiley.1438

smiley.1438

Double post because “Message Body length must be less than 5001.” (…), see the posting before, too.

→ If i didn’t know about WvW matches (which I do), what does b, g, r mean? (yea, I knew it’s blue green red, but I really wouldn’t know)

→ Each map has it’s name (red world, blue world and green world)

I think it’s kinda irrelevant how the identifiers are named – the point is that they have a name so that we can assign them correctly without having to guess (like the scores in match_details.json, see a few posts above). Of course you could name them like “red”, “RedHome” or “red_world_id” but then you would add a lot of overhead again which is not nessecary in this case (not to mention the underscores in the current response instead of camelCasing which add 170 bytes alone).
You said it already: “APIs are made for computers”. (see edit below)

→ But at the cost of making the json not self-explanatory. I really would make some hybrid that anyone can still understand but takes less bandwith than the current one. Else why don’t you just pass binary data instead of json?

What I mean is that APIs are made for computers, so it should be fast for a computer to process the data. But it also has to be understandable for a developer.

It’s always a struggle between a lightweight response and adding too much overhead for having a self descriptive API. The latter thing is less important – thats what API documentations are for, so i’d prefer less overhead for a faster API.
JSON is the weapon of choice nowadays since it’s lightweight and usable in most languages – binary data would be more of a problem for web developers.

The updated gist: https://gist.github.com/codemasher/8876102

Edit:

I’ve added another version of the file with even less overhead and maybe more self-explaining:
https://gist.github.com/codemasher/8876102#file-matches2-json

Edit #2:

While i’m at it, i’ve also created a parsed match_details.json – ~200 bytes smaller than the current and a kittenload more detailed info:
https://gist.github.com/codemasher/8894954
It’s built by this https://github.com/codemasher/gw2api-tools/blob/master/inc/wvw_stats.inc.php (see it live) which i have now ported to Javascript for [SECRET PROJECT].

and using my objectives.json:
https://gist.github.com/codemasher/bac2b4f87e7af128087e

Edit #3:

In the latest version of my objectives.json i’ve dropped the map names (RedHome, BlueHome, GreenHome, Center) in favor of a flat array, so that you can access each item directly without hassle. If you want to keep the sub arrays, you should rather change everey occurence of Red/Blue/GreenHome/Center to their respective map_id to that we can easily merge the data with the mapdata from map_floor.json without having to guess which map belongs to a color.

(edited by smiley.1438)

[API Suggestion] World vs World

in API Development

Posted by: Strategist.6132

Strategist.6132

1. Proper objective names

2. “Contested” boolean for each objective in match details

3. Status of upgrades for each objective in match details

4. Add mercenary camp statuses to match details

5. “Outmanned” list for each map in match details that lists which servers are outmanned on that map (empty list if none)

^^^ this

I agree that expecially the upgrade status and if it’s contested should really be included in the new API’s

[API Suggestion] World vs World

in API Development

Posted by: smiley.1438

smiley.1438

@Devs:

Can you please add the WvW objective icons to the files API (not just the ruins)?