Server time (UTC)
2017-02-24 04:12:05

# 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"
  }
]
```

---