# List students

Section: Game data

```
GET https://ba.joexyz.online/api/v1/students?q=hoshino&school=&club=&attackType=&defenseType=&combatClass=&combatRole=&weaponType=&rarity=&limit=
```

Lists playable students in the default roster order. With `q`, every
student matching the other filters is ranked by a fuzzy match on the name
and search tags, best first, and each result gets a `matchScore`.

Filters take the values used in responses, for example `school=Abydos`
or `combatRole=Tanker`.

**Parameters**

- `q`: Fuzzy search on the name and search tags.
- `school`: `Abydos`, `Arius`, `Gehenna`, `Hyakkiyako`, `Millennium`, `RedWinter`, `Shanhaijing`, `SRT`, `Trinity`, `Valkyrie`, `Highlander`, `WildHunt`, `Odyssey`, `Tokiwadai`, `Sakugawa` or `ETC`.
- `club`: Club, e.g. `Countermeasure`.
- `attackType`: `Explosion`, `Pierce`, `Mystic`, `Sonic`, `Chemical`, `Normal` or `Mixed`, or a color: `red` (Explosion), `yellow` (Pierce), `blue` (Mystic), `purple` (Sonic) or `green` (Chemical).
- `defenseType`: `LightArmor`, `HeavyArmor`, `Unarmed`, `ElasticArmor`, `CompositeArmor`, `Normal` or `Mixed`, or a color: `red` (LightArmor), `yellow` (HeavyArmor), `blue` (Unarmed), `purple` (ElasticArmor) or `green` (CompositeArmor).
- `combatClass`: `Main` (striker) or `Support` (special).
- `combatRole`: `DamageDealer`, `Tanker`, `Healer`, `Supporter` or `Vehicle`.
- `weaponType`: `SR`, `SG`, `AR`, `MG`, `SMG`, `RG`, `HG`, `GL`, `RL`, `FT` or `MT`.
- `rarity`: Initial star rarity, 1–3.
- `limit`: Maximum number of results, 1–500. Defaults to 500.

## Authentication

None

## Query parameters

| Name | Value |
| --- | --- |
| `q` | `hoshino` |
| `school` |  |
| `club` |  |
| `attackType` |  |
| `defenseType` |  |
| `combatClass` |  |
| `combatRole` |  |
| `weaponType` |  |
| `rarity` |  |
| `limit` |  |

## Example responses

### 200 OK

```json
{
  "data": [
    {
      "id": "hoshino",
      "name": "Hoshino",
      "devName": "Hoshino",
      "school": "Abydos",
      "club": "Countermeasure",
      "combatClass": "Main",
      "combatRole": "Tanker",
      "combatPosition": "Front",
      "attackType": "Pierce",
      "defenseType": "HeavyArmor",
      "weaponType": "SG",
      "rarity": 3,
      "searchTags": [
        "ホシノ",
        "おじさん",
        "호시노",
        "星野"
      ],
      "iconUrl": "https://ba.cdn.nimblebun.works/v2/images/students/icons/hoshino.png",
      "portraitUrl": "https://ba.cdn.nimblebun.works/v2/images/students/portraits/hoshino.png",
      "matchScore": 0.989901
    }
  ]
}
```

### 400 Bad Request

```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid query parameters.",
    "details": [
      {
        "path": "rarity",
        "message": "Too big: expected number to be <=3"
      }
    ]
  }
}
```

## Examples

### cURL

```bash
curl 'https://ba.joexyz.online/api/v1/students?q=hoshino&school=&club=&attackType=&defenseType=&combatClass=&combatRole=&weaponType=&rarity=&limit='
```

### JavaScript

```javascript
const response = await fetch("https://ba.joexyz.online/api/v1/students?q=hoshino&school=&club=&attackType=&defenseType=&combatClass=&combatRole=&weaponType=&rarity=&limit=");

const data = await response.json();
console.log(data);
```

### Python

```python
import requests

url = "https://ba.joexyz.online/api/v1/students?q=hoshino&school=&club=&attackType=&defenseType=&combatClass=&combatRole=&weaponType=&rarity=&limit="

response = requests.get(url)
print(response.json())
```

### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://ba.joexyz.online/api/v1/students?q=hoshino&school=&club=&attackType=&defenseType=&combatClass=&combatRole=&weaponType=&rarity=&limit=", nil)
	if err != nil {
		panic(err)
	}

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
```
