# KLR API v2
The KLR API aims to provide consistent and thorough information about the EU-PVP3 server in Naval Action. This document describes how to use it.
---
### Endpoints
* [Server status](#server-status)
* [Nations](#nations)
* [Ports](#ports)
* [Port](#port)
* [Player](#player)
* [Clan](#clan)
* [Conquests](#conquests)
* [Items](#items)
* [Shops](#shops)
### Using the API
##### Responses
All data is returned as JSON with the `application/json` content-type header.
In case an error occurs, a corresponding HTTP status code will be used:
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{"status":404,"message":"Player not found."}
```
The samples below assume successful calls that return a `HTTP 200 OK` response code.
##### Dates
All times are in UTC.
`updated_at` only reflects when the latest _change_ was made to an object, it does not represent whether the data is outdated or not.
##### Caching
We cache our data for at least 10 minutes at a time. You should too. The only exception is `/api/v2/status` which is only cached for a minute.
The larger endpoints are updated daily when the Naval Action servers are down for maintenance. Some data is updated throughout the day in sensible intervals, such as conquests.
##### Data integrity
Some endpoints such as `/api/v2/player` have lower quality data. The data is player-generated and will at times be missing data or return HTTP 404.
---
### Server status
Current status and population.
##### Request
```http
GET /api/v2/status HTTP/1.1
```
##### Response
```js
{
"status":"Maintenance", // Common values: "Update", "Hot fix" and "Working"
"population":"-", // Usually one of "Low", "Medium", and "High"
"date":"2016-04-16" // Implied date. Changes at server maintenance.
}
```
---
### Nations
List available Nation objects.
Updated daily, after server maintenance.
##### Request
```http
GET /api/v2/nations HTTP/1.1
```
##### Response
```js
[
{
"id":0,
"name":"Neutral",
"max_bots":"-1",
"updated_at":"2016-04-06 15:59:32"
},
{
"id":1,
"name":"Pirates",
"max_bots":"-1",
"updated_at":"2016-04-05 06:05:11"
}
]
```
---
### Ports
List available Port objects.
##### Request
```http
GET /api/v2/ports HTTP/1.1
```
##### Response
```js
[
{
"id":133,
"nation_id":7,
"name":"Gustavia",
"capital":true,
"regional":false,
"shallow":false,
"capturer_id":null,
"timeslot":-1,
"lat":"17.895032",
"lng":"-62.848920",
"updated_at":"2016-04-16 12:37:21"
},
{
"id":134,
"nation_id":7,
"name":"Codrington",
"capital":false,
"regional":false,
"shallow":false,
"capturer_id":1023,
"timeslot":20,
"lat":"17.649747",
"lng":"-61.823673",
"updated_at":"2016-04-16 12:37:21"
}
]
```
---
### Port
Detailed information about a port. Includes nested information from related parent objects such as `nation` (derived from `nation_id`)
##### Request
```http
GET /api/v2/port/{id} HTTP/1.1
```
##### Response
```js
{
"id":165,
"nation_id":5,
"name":"Scarborough",
"capital":false,
"regional":false,
"shallow":false,
"capturer_id":677,
"timeslot":-1,
"slug":"scarborough",
"lat":"11.144213",
"lng":"-60.775337",
"updated_at":"2016-04-17 08:32:34",
"nation":{
"id":5,
"name":"Verenigde Provinci\u00ebn",
"max_bots":36,
"updated_at":"2016-04-13 08:16:17"
},
"capturer":{
"id":2,
"name":"Svartschegg",
"nation_id":7,
"clan_id":24,
"slug":"svartschegg",
"created_at":"2016-01-18 00:00:00",
"updated_at":"2016-04-12 13:41:52"
},
"production":[
{
"item_id":42,
"quantity":4,
"item":{
"id":42,
"name":"Silver",
"type":"Resource",
"updated_at":"2016-04-24 10:15:47"
}
}
],
"consumption":[
{
"item_id":300,
"quantity":48,
"item":{
"id":300,
"name":"Live Oak Log",
"type":"Resource",
"updated_at":"2016-04-24 10:15:47"
}
}
],
"shop":[
{
"item_id":27,
"quantity":425,
"buy_price":152,
"sell_price":76,
"contract_buy_quantity":-1,
"contract_sell_quantity":-1,
"updated_at":"2016-04-24 10:16:18",
"item":{
"id":27,
"name":"Gold",
"type":"Resource",
"updated_at":"2016-04-24 10:15:47"
}
}
],
"conquests":[ // 10 latest, regardless of contested (captured) or not
{
"id":1,
"port_id":165,
"nation_id"7,
"player_id":2,
"contested":true,
"created_at":"2016-04-06 15:59:32",
"updated_at":"2016-04-06 16:49:16",
"nation":{
"id":7,
"name":"Sverige",
"max_bots":36,
"updated_at":"2016-04-05 05:53:50"
},
"player":{
"id":2,
"name":"Svartschegg",
"nation_id":null,
"clan_id":24,
"slug":"svartschegg",
"created_at":"2016-01-18 00:00:00",
"updated_at":"2016-04-12 13:41:52"
}
}
]
}
```
---
### Player
View basic information about a player.
*This method may at times return objects with data missing.*
##### Request
By ID:
```http
GET /api/v2/player/{id} HTTP/1.1
```
By name:
```http
GET /api/v2/player/?name={name} HTTP/1.1
```
##### Response
```js
{
"id":2,
"name":"Svartschegg",
"nation_id":null,
"clan_id":24,
"slug":"svartschegg",
"created_at":"2016-01-18 00:00:00", // AKA Birthday
"updated_at":"2016-04-12 13:41:52"
}
```
---
### Clan
View basic information about a clan.
*This method may at times return objects with data missing.*
##### Request
By ID:
```http
GET /api/v2/clan/{id} HTTP/1.1
```
By name:
```http
GET /api/v2/clan/?name={name} HTTP/1.1
```
##### Response
```js
{
"id":24,
"name":"KLR",
"slug":"klr",
"created_at":"2016-01-18 00:00:00",
"members":[
{
"id":2,
"name":"Svartschegg",
"nation_id":null,
"clan_id":24,
"slug":"svartschegg",
"created_at":"2016-01-18 00:00:00",
"updated_at":"2016-04-12 13:41:52"
}
]
}
```
---
### Conquests
Lists conquest objects from the last 24 hours.
##### Request
```http
GET /api/v2/conquests HTTP/1.1
```
##### Response
* `port_id` refers to the defender.
* `nation_id` refers to the attacker.
* `player_id` refers to the attacker.
* `contested` signifies whether the conquest was successful.
```js
[
{
"id":1,
"port_id":183,
"nation_id"7,
"player_id":2,
"contested":true,
"created_at":"2016-04-06 15:59:32",
"updated_at":"2016-04-06 16:49:16",
"nation":{
"id":7,
"name":"Sverige",
"max_bots":36,
"updated_at":"2016-04-05 05:53:50"
},
"player":{
"id":2,
"name":"Svartschegg",
"nation_id":null,
"clan_id":24,
"slug":"svartschegg",
"created_at":"2016-01-18 00:00:00",
"updated_at":"2016-04-12 13:41:52"
}
}
]
```
---
### Items
List available Items.
##### Request
```http
GET /api/v2/items HTTP/1.1
```
##### Response
```js
[
{
"id":1,
"name":"Wooden Fittings",
"type":"Material",
"updated_at":"2016-04-24 10:15:46"
}
]
```
---
