<
* [/regions](#regions)
* [/rounds](#rounds)
* [/statistics](#statistics)
* [/users](#users)
* [/users/location](#usersLocation)
* [/users/top](#usersTop)
* [/zones](#zones)
* [/zones/all](#zonesAll)
_All dates are in [ISO8601](http://en.wikipedia.org/wiki/ISO_8601) time format._
* [API limitations](#limitations)
___
<a name="feeds"></a>
## [v4/feeds](/v4/feeds)
### Request
> GET
OPTIONAL GET PARAMETERS <font color="green">NEW!</font>
> afterDate=2013-08-27T12:11:14+0000
Note that the date needs to be url encoded, so the above date will in have to become
> afterDate=2013-08-27T12%3A11%3A14%2B0000
If this is present, only posts newer than ``afterDate`` will be returned
### GET Response
List of live-data objects ordered by time in descending order, the data can be resetted from time to time and should be handled as an alternative to an rss feed.
There is no specification of number of items returned by each request, it could be from 0 to x.
All feed items contains at least the attributes:
{"time":"???", "type":"???"}
Response:
[
{"type":"takeover", "time":"2013-08-27T12:11:14+0000", {"previousOwner":{"id":654321,"name":"SomeSadPlayer"},"currentOwner":{"id":123467,"name":"SomeHappyPlayer"},"longitude":11.991361,"latitude":57.675559,"zone":{"name":"Plattan", ...}},
{"type":"medal", "time":"2013-08-27T11:57:56+0000", "medal":6, "user":{"name":"SomeHappyPlayer", ...}},
{"type":"chat", "time":"2013-08-27T11:14:12+0000", "message":"Chat message text ", "region":{"id":129,"name":"Dalarna"}, "country":"se", "sender":{"name":"playername", ...}},
{"type":"zone", "time":"2013-08-27T14:00:28+0000", "zone":{"name":"Allebadet", ...}},
...
]
Current feed types:
- "takeover": Shows latest takeovers within the last 30 minutes.
- "medal": Shows latest earned medal by user
- "chat": Shows latest chat messages in game
- "zone": Shows latest created zones in the game
Its also possible to filter feed types by entering the feed types you want to show
Examples:
[v4/feeds/takeover](/v4/feeds/takeover) returns feed with only takeover types
[v4/feeds/chat+medal](/v4/feeds/chat+medal) returns feed with medals and chat messages only.
___
<a name="regions"></a>
## [v4/regions](/v4/regions)
### Request
> GET
### GET Response
Returns all regions with current regionlords
[{"id":141,"name":"Stockholm","country":"se","regionLord":{"id":14022,"name":"Pelle494"}}, ...]
___
<a name="rounds"></a>
## [v4/rounds](/v4/rounds)
### Request
> GET
### GET Response
Returns monthly turf round start times.
[{ "start":"2013-09-01T10:00:00+0000", "name":"September" }, ... ]
___
<a name="statistics"></a>
## [v4/statistics](/v4/statistics)
Returns current game statistics.
### Request
> GET
### Response
BODY
{"zonesTakenYesterday":10505,"totalZonesTaken":3061709,"activeUsersThisRound":1451,"zonesTakenToday":7466,"usersOnline":84,"zonesTakenThisRound":78233,"totalUsers":38589}
___
<a name="users"></a>
## [v4/users](/v4/users)
### Request
> POST
Required Headers
Content-Type: application/json
BODY
[{"name" : "fredrick"}, ...]
OR
[{"id" : 1803}, ...]
OR
[{"email" : "turfer...@gmail.com"}, ...]
OR
[{"name" : "fredrick"}, {"email" : "turfer...@gmail.com"}, {"id" : 1803}, ...]
### Response
BODY
[{"region":{"id":141,"name":"Stockholm"},"medals":[5,9,7,36,28,4,20,24,22,25,14,17,16,17,48,17,57,62],"blocktime":30,"zones":[2428,2988,16852,7152,355,1106,16900],"uniqueZonesTaken":205,"id":1803,"pointsPerHour":31,"rank":42,"totalPoints":1976318,"name":"Fredrick","taken":7402,"points":75964,"place":15,"country":"se"}, ...]
THROWS (Status: 400 Bad Request)
//If POST string is invalid
{ "errorMessage" : "Invalid JSON string" , "errorCode" : 0xBAD0001 }
___
<a name="usersLocation"></a>
## [v4/users/location](/v4/users/location)
### Request
> GET
### GET Response
Returns current players that has a location on the game map
[{ "id":14242, "name":"turfername" , "longitude":16.552683 , "latitude":59.604117 }, ... ]
___
<a name="usersTop"></a>
## [v4/users/top](/v4/users/top)
### Request
> GET, POST
Required Headers for POST
Content-Type: application/json
POST BODY
{"from": 1, "to": 10}
OR
{"country": "se", "from": 1, "to": 10}
OR
{"region": "kalmar", "from": 1, "to": 10}
### GET Response
Returns top 50 users in order, see __/users__ for all the user parameters available
[{"name":"leader", "place":1, ...}, {"name":"runnerup", "place":2, ...}, ...]
### POST Response
BODY
Returns the users in toplist order for the corresponding region or country with the "place" variable localized
[{"name":"leader", "place":1, ...}, {"name":"runnerup", "place":2, ...}, ...]
THROWS (Status: 400 Bad Request)
//If POST string is invalid
{ "errorMessage" : "Invalid JSON string" , "errorCode" : 0xBAD0001 }
___
<a name="zones"></a>
## [v4/zones](/v4/zones)
Query the API for any zone in the game.
### Request
> POST
Required Headers
Content-Type: application/json
BODY
[{"name" : "plattan"}, ...]
OR
[{"id" : 138}, ...]
OR
[{"id" : 138}, {"name":"plattan"} ...]
OR
// Return all zones within an area
[{
"northEast" : {"latitude":59.339881, "longitude":18.086243},
"southWest" : {"latitude":59.313259, "longitude":18.048477}
}]
### Response
BODY
[{"region":{"id":141,"name":"Stockholm"},"id":138,"currentOwner":{"id":14022,"name":"Pelle494"},"totalTakeovers":6278,"takeoverPoints":65,"dateLastTaken":"2013-06-08T12:59:19+0000","name":"Plattan","pointsPerHour":9,"dateCreated":"2010-09-04T16:41:37+0000","longitude":18.064098,"latitude":59.33225}, ...]
THROWS (Status: 400 Bad Request)
//If POST string is invalid
{ "errorMessage" : "Invalid JSON string", "errorCode" : 0xBAD0001 }
//If the area is too big
if ( northEast["latitude"] - southWest["latitude"] ) * ( northEast["longitude"] - southWest["longitude"] ) > 0.05
{ "errorMessage" : "The area is too big", "errorCode" : 0xBAD0002 }
//If the area-coordinates arent creating a valid area
{ "errorMessage" : "Invalid coordinates", "errorCode" : 0xBAD0003 }
___
<a name="zonesAll"></a>
## [v4/zones/all](/v4/zones/all)
Returns all the zones in the game. The list updates at least once an hour.
### Request
> GET
### Response
BODY
[{"region":{"id":143,"name":"Västmanland","country":"se"},"id":21355,"totalTakeovers":8,"takeoverPoints":170,"name":"SätraWell","pointsPerHour":2,"dateCreated":"2013-08-19T08:59:42+0000","longitude":16.448538,"latitude":59.860708}, ...]
___
THROWS (Status: 429 Too many requests)
//If queries twice within 30 minutes
{"errorMessage":"Only one request per 30 minutes allowed","errorCode":0xBAD0004}
## Optional, but recommended header value for all API calls
Accept-Encoding: gzip
___
<a name="limitations"></a>
## API limitations
> Only one request per second per resource is currently allowed. This might change in the future depending on API usage.
THROWS (Status: 429 Too many requests)
{"errorMessage":"Only one request per second allowed","errorCode":0xBAD0004}
___
# API versions
Old API versions are still available but its NOT recommended to use them, they might not be maintained in the future.
For a sneak peek of the latest API version, goto [api.turfgame.com/unstable](/unstable)]]>