v0.1.1 -
feat: collector task checklist. chore: docs updated, gitignore updated. Docs: TARKOV_DEV_API.md fully explains tarkov.dev's api for future coding agents and forgetful people llike me.
This commit is contained in:
serversdwn
458
TARKOV_DEV_API.md
Normal file
458
TARKOV_DEV_API.md
Normal file
@@ -0,0 +1,458 @@
|
||||
# tarkov.dev GraphQL API Reference
|
||||
|
||||
> Community-made, real-time EFT data. No API key required.
|
||||
|
||||
- **Endpoint:** `https://api.tarkov.dev/graphql`
|
||||
- **Playground:** `https://api.tarkov.dev/` (interactive explorer with autocomplete)
|
||||
- **Protocol:** GraphQL over HTTP POST
|
||||
- **Auth:** None — completely open
|
||||
- **Source:** https://github.com/the-hideout/tarkov-api
|
||||
|
||||
---
|
||||
|
||||
## How to query (Python)
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
API_URL = "https://api.tarkov.dev/graphql"
|
||||
|
||||
def gql(query):
|
||||
r = requests.post(API_URL, json={"query": query})
|
||||
r.raise_for_status()
|
||||
data = r.json()
|
||||
if "errors" in data:
|
||||
raise RuntimeError(data["errors"])
|
||||
return data["data"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common arguments (most queries accept these)
|
||||
|
||||
| Arg | Type | Notes |
|
||||
|------------|----------------|--------------------------------------------|
|
||||
| `lang` | `LanguageCode` | e.g. `en`, `ru`, `de`, `fr`, `es`, `zh` |
|
||||
| `gameMode` | `GameMode` | `regular` or `pve` |
|
||||
| `limit` | `Int` | Max results to return |
|
||||
| `offset` | `Int` | Pagination offset |
|
||||
|
||||
---
|
||||
|
||||
## All available root queries
|
||||
|
||||
```
|
||||
achievements(lang, limit, offset)
|
||||
ammo(lang, gameMode, limit, offset)
|
||||
archivedItemPrices(id, limit, offset)
|
||||
barters(lang, gameMode, limit, offset)
|
||||
bosses(lang, gameMode, name, limit, offset)
|
||||
crafts(lang, gameMode, limit, offset)
|
||||
fleaMarket(lang, gameMode)
|
||||
goonReports(lang, gameMode, limit, offset)
|
||||
handbookCategories(lang, limit, offset)
|
||||
hideoutStations(lang, gameMode, limit, offset)
|
||||
historicalItemPrices(id, days, lang, gameMode, limit, offset)
|
||||
item(id, normalizedName, lang, gameMode)
|
||||
items(ids, name, names, type, types, categoryNames, handbookCategoryNames, bsgCategoryId, bsgCategoryIds, bsgCategory, lang, gameMode, limit, offset)
|
||||
itemCategories(lang, limit, offset)
|
||||
itemPrices(id, gameMode, limit, offset)
|
||||
lootContainers(lang, limit, offset)
|
||||
maps(lang, gameMode, name, enemies, limit, offset)
|
||||
mastering(lang)
|
||||
playerLevels()
|
||||
prestige(lang, gameMode)
|
||||
questItems(lang)
|
||||
skills(lang)
|
||||
stationaryWeapons(lang, limit, offset)
|
||||
status()
|
||||
task(id, lang, gameMode)
|
||||
tasks(faction, lang, gameMode, limit, offset)
|
||||
traders(lang, gameMode, limit, offset)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Query examples
|
||||
|
||||
### Server status
|
||||
```graphql
|
||||
{
|
||||
status {
|
||||
currentStatuses {
|
||||
name
|
||||
message
|
||||
status
|
||||
}
|
||||
messages {
|
||||
time
|
||||
type
|
||||
content
|
||||
solveTime
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Single item by name
|
||||
```graphql
|
||||
{
|
||||
items(name: "colt m4a1") {
|
||||
id
|
||||
name
|
||||
shortName
|
||||
basePrice
|
||||
avg24hPrice
|
||||
changeLast48hPercent
|
||||
width
|
||||
height
|
||||
weight
|
||||
wikiLink
|
||||
iconLink
|
||||
gridImageLink
|
||||
sellFor {
|
||||
price
|
||||
currency
|
||||
source
|
||||
}
|
||||
buyFor {
|
||||
price
|
||||
currency
|
||||
source
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Items by type (e.g. all keys)
|
||||
```graphql
|
||||
{
|
||||
items(types: [keys]) {
|
||||
id
|
||||
name
|
||||
shortName
|
||||
wikiLink
|
||||
gridImageLink
|
||||
properties {
|
||||
... on ItemPropertiesKey {
|
||||
uses
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Valid `ItemType` values include: `keys`, `ammo`, `armor`, `backpack`, `gun`, `headwear`, `rig`, `medical`, `food`, `barter`, `container`, `grenade`, `headphones`, `knife`, `stimulator`, `suppressor`, `weapon`
|
||||
|
||||
### All tasks / quests
|
||||
```graphql
|
||||
{
|
||||
tasks {
|
||||
id
|
||||
name
|
||||
wikiLink
|
||||
minPlayerLevel
|
||||
kappaRequired
|
||||
trader {
|
||||
name
|
||||
}
|
||||
taskRequirements {
|
||||
task {
|
||||
id
|
||||
name
|
||||
}
|
||||
status
|
||||
}
|
||||
objectives {
|
||||
id
|
||||
type
|
||||
description
|
||||
maps {
|
||||
name
|
||||
normalizedName
|
||||
}
|
||||
... on TaskObjectiveItem {
|
||||
item { name shortName }
|
||||
count
|
||||
foundInRaid
|
||||
}
|
||||
... on TaskObjectiveShoot {
|
||||
targetNames
|
||||
count
|
||||
}
|
||||
... on TaskObjectiveLocation {
|
||||
locationNames
|
||||
}
|
||||
... on TaskObjectiveQuestItem {
|
||||
questItem { name }
|
||||
count
|
||||
}
|
||||
... on TaskObjectiveSkill {
|
||||
skillLevel { name level }
|
||||
}
|
||||
... on TaskObjectiveTraderLevel {
|
||||
trader { name }
|
||||
level
|
||||
}
|
||||
}
|
||||
startRewards {
|
||||
items { item { name } count }
|
||||
traderStanding { trader { name } standing }
|
||||
}
|
||||
finishRewards {
|
||||
items { item { name } count }
|
||||
experience
|
||||
traderStanding { trader { name } standing }
|
||||
offerUnlock { trader { name } item { name } }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** `objectives` returns a `TaskObjective` **interface** — use inline fragments (`... on TypeName`) to access type-specific fields.
|
||||
|
||||
### Single task by ID
|
||||
```graphql
|
||||
{
|
||||
task(id: "5936d90786f7742b1420ba5b") {
|
||||
name
|
||||
trader { name }
|
||||
taskRequirements { task { id name } }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Ammo stats
|
||||
```graphql
|
||||
{
|
||||
ammo {
|
||||
item { name shortName }
|
||||
caliber
|
||||
damage
|
||||
armorDamage
|
||||
penetrationPower
|
||||
penetrationChance
|
||||
fragmentationChance
|
||||
initialSpeed
|
||||
lightBleedModifier
|
||||
heavyBleedModifier
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Traders
|
||||
```graphql
|
||||
{
|
||||
traders {
|
||||
id
|
||||
name
|
||||
normalizedName
|
||||
currency { name }
|
||||
levels {
|
||||
level
|
||||
requiredPlayerLevel
|
||||
requiredReputation
|
||||
requiredCommerce
|
||||
cashOffers {
|
||||
item { name }
|
||||
price
|
||||
currency
|
||||
minTraderLevel
|
||||
taskUnlock { name }
|
||||
}
|
||||
}
|
||||
barters {
|
||||
requiredItems { item { name } count }
|
||||
rewardItems { item { name } count }
|
||||
minTraderLevel
|
||||
taskUnlock { name }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Hideout stations
|
||||
```graphql
|
||||
{
|
||||
hideoutStations {
|
||||
id
|
||||
name
|
||||
levels {
|
||||
level
|
||||
constructionTime
|
||||
itemRequirements { item { name } count }
|
||||
stationLevelRequirements { station { name } level }
|
||||
skillRequirements { skill { name } level }
|
||||
traderRequirements { trader { name } requirementType value }
|
||||
bonuses { type value }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Maps
|
||||
```graphql
|
||||
{
|
||||
maps {
|
||||
id
|
||||
name
|
||||
normalizedName
|
||||
raidDuration
|
||||
players
|
||||
bosses {
|
||||
boss { name }
|
||||
spawnChance
|
||||
spawnLocations { name chance }
|
||||
escorts { boss { name } amount { count chance } }
|
||||
}
|
||||
extracts {
|
||||
name
|
||||
faction
|
||||
switches { name }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Crafts
|
||||
```graphql
|
||||
{
|
||||
crafts {
|
||||
station { name }
|
||||
level
|
||||
duration
|
||||
requiredItems { item { name } count }
|
||||
rewardItems { item { name } count }
|
||||
taskUnlock { name }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Barters
|
||||
```graphql
|
||||
{
|
||||
barters {
|
||||
trader { name }
|
||||
level
|
||||
taskUnlock { name }
|
||||
requiredItems { item { name } count }
|
||||
rewardItems { item { name } count }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Flea market info
|
||||
```graphql
|
||||
{
|
||||
fleaMarket {
|
||||
enabled
|
||||
minPlayerLevel
|
||||
sellOfferFeeRate
|
||||
sellRequirementFeeRate
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Achievements
|
||||
```graphql
|
||||
{
|
||||
achievements {
|
||||
id
|
||||
name
|
||||
description
|
||||
hidden
|
||||
rarity
|
||||
playersCompletedPercent
|
||||
side
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Goon reports (roaming boss locations)
|
||||
```graphql
|
||||
{
|
||||
goonReports {
|
||||
map { name }
|
||||
timestamp
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key types reference
|
||||
|
||||
### Item fields
|
||||
```
|
||||
id, name, shortName, normalizedName
|
||||
basePrice, avg24hPrice, low24hPrice, high24hPrice
|
||||
changeLast48h, changeLast48hPercent
|
||||
lastLowPrice, lastOfferCount
|
||||
width, height, weight, velocity
|
||||
wikiLink, iconLink, gridImageLink, inspectImageLink, image8xLink
|
||||
types[] – ItemType enum values this item belongs to
|
||||
sellFor[] – { price, currency, source, vendor { name } }
|
||||
buyFor[] – { price, currency, source, vendor { name } }
|
||||
bartersFor[] – Barter objects
|
||||
bartersUsing[] – Barter objects
|
||||
usedInTasks[] – Task objects
|
||||
receivedFromTasks[] – Task objects
|
||||
properties – ItemProperties union (see below)
|
||||
category – { id, name }
|
||||
```
|
||||
|
||||
### ItemProperties union types
|
||||
Use `... on ItemPropertiesX { }` inline fragments:
|
||||
- `ItemPropertiesKey` → `uses`
|
||||
- `ItemPropertiesAmmo` → `caliber, damage, penetrationPower, ...`
|
||||
- `ItemPropertiesArmor` → `class, durability, material, zones[]`
|
||||
- `ItemPropertiesArmorAttachment` → `class, durability, material, zones[], headCoverage`
|
||||
- `ItemPropertiesBackpack` → `capacity, grids[]`
|
||||
- `ItemPropertiesChestRig` → `capacity, class, durability, zones[]`
|
||||
- `ItemPropertiesWeapon` → `caliber, fireRate, ergonomics, recoil...`
|
||||
- `ItemPropertiesMagazine` → `capacity, caliber, ergonomics`
|
||||
- `ItemPropertiesScope` → `ergonomics, recoil, zoomLevels[]`
|
||||
- `ItemPropertiesMedKit` → `uses, useTime, hpCostLightBleeding, hpCostHeavyBleeding`
|
||||
- `ItemPropertiesFood` → `energy, hydration, stimEffects[]`
|
||||
- `ItemPropertiesStimulator` → `stimEffects[]`
|
||||
- `ItemPropertiesHelmet` → `class, durability, material, headZones[], deafening`
|
||||
- `ItemPropertiesGlasses` → `class, durability, blindnessProtection`
|
||||
- `ItemPropertiesNightVision` → `intensity, noiseIntensity, noiseScale`
|
||||
- `ItemPropertiesContainer` → `capacity`
|
||||
- `ItemPropertiesGrenade` → `type, fuse, fragments, minExplosionDistance, maxExplosionDistance`
|
||||
|
||||
### Task / quest fields
|
||||
```
|
||||
id, name, normalizedName
|
||||
wikiLink
|
||||
minPlayerLevel
|
||||
kappaRequired – bool, whether needed for Kappa (The Collector)
|
||||
restartable
|
||||
trader { id, name }
|
||||
map { id, name } – nullable, map-specific tasks only
|
||||
experience
|
||||
taskRequirements[] – { task { id, name }, status[] }
|
||||
objectives[] – TaskObjective interface (use inline fragments)
|
||||
startRewards – TaskRewards
|
||||
finishRewards – TaskRewards
|
||||
```
|
||||
|
||||
### TaskRewards fields
|
||||
```
|
||||
items[] – { item { name }, count }
|
||||
traderStanding[] – { trader { name }, standing }
|
||||
offerUnlock[] – { trader { name }, level, item { name } }
|
||||
skillLevelReward[] – { name, level }
|
||||
craftUnlock[] – craft objects
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How we use it in this project
|
||||
|
||||
| Script | Query | Purpose |
|
||||
|---|---|---|
|
||||
| [import_keys.py](import_keys.py) | `items(types: [keys])` | Fetches all key items into `keys` table |
|
||||
| [import_quests.py](import_quests.py) | `tasks { id name wikiLink trader taskRequirements }` | Fetches all tasks and their dependencies into `quests` + `quest_deps` tables |
|
||||
|
||||
The Collector prerequisite tree is computed from `quest_deps` using a recursive SQL CTE in [app.py](app.py) at `/collector`.
|
||||
Reference in New Issue
Block a user