{"openapi":"3.1.0","info":{"title":"Chess Openings API","version":"1.0.0","description":"The Encyclopaedia of Chess Openings (ECO) as an API — 3,161 named chess openings and variations with their ECO code (A00–E99), full name, family/variation and the exact move sequence (PGN and a clean move list). Search openings by name, ECO code or ECO volume; list every opening under a code (e.g. B20 → 27 Sicilian lines); pick a random opening; and — the killer feature — identify which opening a game is in from a sequence of moves (e.g. \"1. e4 c5 2. Nf3\" → Sicilian Defense). Ideal for chess apps, game analysis, training tools, bots and trivia. Open data from the lichess-org/chess-openings project.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/chessopenings-api","description":"oanor gateway"}],"tags":[{"name":"Chess Openings"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/eco":{"get":{"operationId":"get_v1_eco","tags":["Chess Openings"],"summary":"All openings with a given ECO code","description":"","parameters":[{"name":"code","in":"query","required":true,"description":"ECO code, e.g. B20","schema":{"type":"string"},"example":"B20"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"eco":"B20","count":27,"openings":[{"eco":"B20","pgn":"1. e4 c5","ply":2,"name":"Sicilian Defense","moves":["e4","c5"],"family":"Sicilian Defense","volume":"B"},{"eco":"B20","pgn":"1. e4 c5 2. Qg4","ply":3,"name":"Sicilian Defense: Amazon Attack","moves":["e4","c5","Qg4"],"family":"Sicilian Defense","volume":"B","variation":"Amazon Attack"},{"eco":"B20","pgn":"1. e4 c5 2. d3 Nc6 3. c3 d6 4. f4","ply":7,"name":"Sicilian Defense: Big Clamp Formation","moves":["e4","c5","d3","Nc6","c3","d6","f4"],"family":"Sicilian Defense","volume":"B","variation":"Big Clamp Formation"},{"eco":"B20","pgn":"1. e4 c5 2. Bc4","ply":3,"name":"Sicilian Defense: Bowdler Attack","moves":["e4","c5","Bc4"],"family":"Sicilian Defense","volume":"B","variation":"Bowdler Attack"},{"eco":"B20","pgn":"1. e4 c5 2. Nh3","ply":3,"name":"Sicilian Defense: Brick Variation","moves":["e4","c5","Nh3"],"family":"Sicilian Defense","volume":"B","variation":"Brick Variation"},{"eco":"B20","pgn":"1. e4 c5 2. b3","ply":3,"name":"Sicilian Defense: Czerniak Attack","moves":["e4","c5","b3"],"family":"Sicilian Defense","volume":"B","variation":"Czerniak Attack"},{"eco":"B20","pgn":"1. e4 c5 2. b3 b6","ply":4,"name":"Sicilian Defense: Czerniak Attack, Queen Fianchetto Variation","moves":["e4","c5","b3","b6"],"family":"Sicilian Defense","volume":"B","variation":"Czerniak Attack, Queen Fianchetto Variation"},{"eco":"B20","pgn":"1. e4 c5 2. b3 d5 3. Bb2","ply":5,"name":"Sicilian Defense: Euwe Attack, Prins Gambit","moves":["e4","c5","b3","d5","Bb2"],"family":"Sicilian Defense","volume":"B","variation":"Euwe Attack, Prins Gambit"},{"eco":"B20","pgn":"1. e4 c5 2. c4 d6 3. Nc3 Nc6 4. g3 h5","ply":8,"name":"Sicilian Defense: Gloria Variation","moves":["e4","c5","c4","d6","Nc3","Nc6","g3","h5"],"family":"Sicilian Defense","volume":"B","variation":"Gloria Variation"},{"eco":"B20","pgn":"1. e4 c5 2. g4","ply":3,"name":"Sicilian Defense: Grob Variation","moves":["e4","c5","g4"],"family":"Sicilian Defense","volume":"B","variation":"Grob Variation"},{"eco":"B20","pgn":"1. e4 c5 2. Ne2","ply":3,"name":"Sicilian Defense: Keres Variation","moves":["e4","c5","Ne2"],"family":"Sicilian Defense","volume":"B","variation":"Keres Variation"},{"eco":"B20","pgn":"1. e4 c5 2. Ke2","ply":3,"name":"Sicilian Defense: King David's Opening","moves":["e4","c5","Ke2"],"family":"Sicilian Defense","volume":"B","variation":"King David's Opening"},{"eco":"B20","pgn":"1. e4 c5 2. Na3","ply":3,"name":"Sicilian Defense: Kronberger Variation","moves":["e4","c5","Na3"],"family":"Sicilian Defense","volume":"B","variation":"Kronberger Variation"},{"eco":"B20","pgn":"1. e4 c5 2. Na3 Nc6 3. d4 cxd4 4. Bc4","ply":7,"name":"Sicilian Defense: Kronberger Variation, Nemeth Gambit","moves":["e4","c5","Na3","Nc6","d4","cxd4","Bc4"],"family":"Sicilian Defense","volume":"B","variation":"Kronberger Variation, Nemeth Gambit"},{"eco":"B20","pgn":"1. e4 c5 2. g3","ply":3,"name":"Sicilian Defense: Lasker-Dunne Attack","moves":["e4","c5","g3"],"family":"Sicilian Defense","volume":"B","variation":"Lasker-Dunne Attack"},{"eco":"B20","pgn":"1. e4 c5 2. a3","ply":3,"name":"Sicilian Defense: Mengarini Variation","moves":["e4","c5","a3"],"family":"Sicilian Defense","volume":"B","variation":"Mengarini Variation"},{"eco":"B20","pgn":"1. e4 c5 2. a4","ply":3,"name":"Sicilian Defense: Myers Attack, with a4","moves":["e4","c5","a4"],"family":"Sicilian Defense","volume":"B","variation":"Myers Attack, with a4"},{"eco":"B20","pgn":"1. e4 c5 2. h4","ply":3,"name":"Sicilian Defense: Myers Attack, with h4","moves":["e4","c5","h4"],"family":"Sicilian Defense","volume":"B","variation":"Myers Attack, with h4"},{"eco":"B20","pgn":"1. e4 c5 2. c4","ply":3,"name":"Sicilian Defense: Staunton-Cochrane Variation","moves":["e4","c5","c4"],"family":"Sicilian Defense","volume":"B","variation":"Staunton-Cochrane Variation"},{"eco":"B20","pgn":"1. e4 c5 2. b4","ply":3,"name":"Sicilian Defense: Wing Gambit","moves":["e4","c5","b4"],"family":"Sicilian Defense","volume":"B","variation":"Wing Gambit"},{"eco":"B20","pgn":"1. e4 c5 2. b4 cxb4 3. Bb2","ply":5,"name":"Sicilian Defense: Wing Gambit, Abrahams Variation","moves":["e4","c5","b4","cxb4","Bb2"],"family":"Sicilian Defense","volume":"B","variation":"Wing Gambit, Abrahams Variation"},{"eco":"B20","pgn":"1. e4 c5 2. b4 cxb4 3. a3 bxa3","ply":6,"name":"Sicilian Defense: Wing Gambit, Carlsbad Variation","moves":["e4","c5","b4","cxb4","a3","bxa3"],"family":"Sicilian Defense","volume":"B","variation":"Wing Gambit, Carlsbad Variation"},{"eco":"B20","pgn":"1. e4 c5 2. b4 cxb4 3. a3 d5 4. exd5 Qxd5 5. Bb2","ply":9,"name":"Sicilian Defense: Wing Gambit, Marienbad Variation","moves":["e4","c5","b4","cxb4","a3","d5","exd5","Qxd5","Bb2"],"family":"Sicilian Defense","volume":"B","variation":"Wing Gambit, Marienbad Variation"},{"eco":"B20","pgn":"1. e4 c5 2. b4 cxb4 3. a3","ply":5,"name":"Sicilian Defense: Wing Gambit, Marshall Variation","moves":["e4","c5","b4","cxb4","a3"],"family":"Sicilian Defense","volume":"B","variation":"Wing Gambit, Marshall Variation"},{"eco":"B20","pgn":"1. e4 c5 2. b4 cxb4 3. a3 d5 4. exd5 Qxd5 5. Nf3 e5 6. c4 Qe6 7. Bd3","ply":13,"name":"Sicilian Defense: Wing Gambit, Nanu Gambit","moves":["e4","c5","b4","cxb4","a3","d5","exd5","Qxd5","Nf3","e5","c4","Qe6","Bd3"],"family":"Sicilian Defense","volume":"B","variation":"Wing Gambit, Nanu Gambit"},{"eco":"B20","pgn":"1. e4 c5 2. b4 cxb4 3. a3 d5 4. exd5 Qxd5 5. Nf3 e5 6. Bb2 Nc6 7. c4 Qe6","ply":14,"name":"Sicilian Defense: Wing Gambit, Romanian Defense","moves":["e4","c5","b4","cxb4","a3","d5","exd5","Qxd5","Nf3","e5","Bb2","Nc6","c4","Qe6"],"family":"Sicilian Defense","volume":"B","variation":"Wing Gambit, Romanian Defense"},{"eco":"B20","pgn":"1. e4 c5 2. b4 cxb4 3. c4","ply":5,"name":"Sicilian Defense: Wing Gambit, Santasiere Variation","moves":["e4","c5","b4","cxb4","c4"],"family":"Sicilian Defense","volume":"B","variation":"Wing Gambit, Santasiere Variation"}]},"meta":{"timestamp":"2026-05-31T09:34:54.832Z","request_id":"692cb7d9-09c3-44ca-a8b7-79017e0cd175"},"status":"ok","message":"Openings by ECO code","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/identify":{"get":{"operationId":"get_v1_identify","tags":["Chess Openings"],"summary":"Identify the opening from a move sequence","description":"","parameters":[{"name":"moves","in":"query","required":true,"description":"Moves in SAN/PGN, e.g. 1. e4 c5 2. Nf3","schema":{"type":"string"},"example":"1. e4 c5 2. Nf3"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"exact":false,"opening":{"eco":"B20","pgn":"1. e4 c5","ply":2,"name":"Sicilian Defense","moves":["e4","c5"],"family":"Sicilian Defense","volume":"B"},"input_ply":3,"matched_ply":2},"meta":{"timestamp":"2026-05-31T09:34:54.905Z","request_id":"4430efd6-380c-4014-ab15-5c3665121029"},"status":"ok","message":"Opening identified","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/random":{"get":{"operationId":"get_v1_random","tags":["Chess Openings"],"summary":"A random opening","description":"","parameters":[{"name":"volume","in":"query","required":false,"description":"Restrict to ECO volume A-E","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"opening":{"eco":"E36","pgn":"1. d4 Nf6 2. c4 e6 3. Nc3 Bb4 4. Qc2 d5 5. a3 Bxc3+ 6. Qxc3 Ne4","ply":12,"name":"Nimzo-Indian Defense: Classical Variation, Noa Variation, Main Line","moves":["d4","Nf6","c4","e6","Nc3","Bb4","Qc2","d5","a3","Bxc3+","Qxc3","Ne4"],"family":"Nimzo-Indian Defense","volume":"E","variation":"Classical Variation, Noa Variation, Main Line"}},"meta":{"timestamp":"2026-05-31T09:34:54.986Z","request_id":"83348a25-604e-42a4-b5f1-b8383f8d219c"},"status":"ok","message":"Random opening","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/search":{"get":{"operationId":"get_v1_search","tags":["Chess Openings"],"summary":"Search & filter openings","description":"","parameters":[{"name":"q","in":"query","required":false,"description":"Search by opening name","schema":{"type":"string"},"example":"sicilian"},{"name":"eco","in":"query","required":false,"description":"Exact ECO code, e.g. B20","schema":{"type":"string"}},{"name":"volume","in":"query","required":false,"description":"ECO volume A, B, C, D or E","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page (1-100, default 20)","schema":{"type":"string"},"example":"20"},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"string"},"example":"0"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":20,"limit":20,"total":344,"offset":0,"filters":{"q":"sicilian"},"results":[{"eco":"B20","pgn":"1. e4 c5","ply":2,"name":"Sicilian Defense","moves":["e4","c5"],"family":"Sicilian Defense","volume":"B"},{"eco":"B20","pgn":"1. e4 c5 2. Qg4","ply":3,"name":"Sicilian Defense: Amazon Attack","moves":["e4","c5","Qg4"],"family":"Sicilian Defense","volume":"B","variation":"Amazon Attack"},{"eco":"B20","pgn":"1. e4 c5 2. Bc4","ply":3,"name":"Sicilian Defense: Bowdler Attack","moves":["e4","c5","Bc4"],"family":"Sicilian Defense","volume":"B","variation":"Bowdler Attack"},{"eco":"B20","pgn":"1. e4 c5 2. Nh3","ply":3,"name":"Sicilian Defense: Brick Variation","moves":["e4","c5","Nh3"],"family":"Sicilian Defense","volume":"B","variation":"Brick Variation"},{"eco":"B20","pgn":"1. e4 c5 2. b3","ply":3,"name":"Sicilian Defense: Czerniak Attack","moves":["e4","c5","b3"],"family":"Sicilian Defense","volume":"B","variation":"Czerniak Attack"},{"eco":"B20","pgn":"1. e4 c5 2. g4","ply":3,"name":"Sicilian Defense: Grob Variation","moves":["e4","c5","g4"],"family":"Sicilian Defense","volume":"B","variation":"Grob Variation"},{"eco":"B20","pgn":"1. e4 c5 2. Ne2","ply":3,"name":"Sicilian Defense: Keres Variation","moves":["e4","c5","Ne2"],"family":"Sicilian Defense","volume":"B","variation":"Keres Variation"},{"eco":"B20","pgn":"1. e4 c5 2. Ke2","ply":3,"name":"Sicilian Defense: King David's Opening","moves":["e4","c5","Ke2"],"family":"Sicilian Defense","volume":"B","variation":"King David's Opening"},{"eco":"B20","pgn":"1. e4 c5 2. Na3","ply":3,"name":"Sicilian Defense: Kronberger Variation","moves":["e4","c5","Na3"],"family":"Sicilian Defense","volume":"B","variation":"Kronberger Variation"},{"eco":"B20","pgn":"1. e4 c5 2. g3","ply":3,"name":"Sicilian Defense: Lasker-Dunne Attack","moves":["e4","c5","g3"],"family":"Sicilian Defense","volume":"B","variation":"Lasker-Dunne Attack"},{"eco":"B20","pgn":"1. e4 c5 2. a3","ply":3,"name":"Sicilian Defense: Mengarini Variation","moves":["e4","c5","a3"],"family":"Sicilian Defense","volume":"B","variation":"Mengarini Variation"},{"eco":"B20","pgn":"1. e4 c5 2. a4","ply":3,"name":"Sicilian Defense: Myers Attack, with a4","moves":["e4","c5","a4"],"family":"Sicilian Defense","volume":"B","variation":"Myers Attack, with a4"},{"eco":"B20","pgn":"1. e4 c5 2. h4","ply":3,"name":"Sicilian Defense: Myers Attack, with h4","moves":["e4","c5","h4"],"family":"Sicilian Defense","volume":"B","variation":"Myers Attack, with h4"},{"eco":"B20","pgn":"1. e4 c5 2. c4","ply":3,"name":"Sicilian Defense: Staunton-Cochrane Variation","moves":["e4","c5","c4"],"family":"Sicilian Defense","volume":"B","variation":"Staunton-Cochrane Variation"},{"eco":"B20","pgn":"1. e4 c5 2. b4","ply":3,"name":"Sicilian Defense: Wing Gambit","moves":["e4","c5","b4"],"family":"Sicilian Defense","volume":"B","variation":"Wing Gambit"},{"eco":"B21","pgn":"1. e4 c5 2. f4","ply":3,"name":"Sicilian Defense: McDonnell Attack","moves":["e4","c5","f4"],"family":"Sicilian Defense","volume":"B","variation":"McDonnell Attack"},{"eco":"B21","pgn":"1. e4 c5 2. d4","ply":3,"name":"Sicilian Defense: Smith-Morra Gambit","moves":["e4","c5","d4"],"family":"Sicilian Defense","volume":"B","variation":"Smith-Morra Gambit"},{"eco":"B22","pgn":"1. e4 c5 2. c3","ply":3,"name":"Sicilian Defense: Alapin Variation","moves":["e4","c5","c3"],"family":"Sicilian Defense","volume":"B","variation":"Alapin Variation"},{"eco":"B23","pgn":"1. e4 c5 2. Nc3","ply":3,"name":"Sicilian Defense: Closed","moves":["e4","c5","Nc3"],"family":"Sicilian Defense","volume":"B","variation":"Closed"},{"eco":"B20","pgn":"1. e4 c5 2. b3 b6","ply":4,"name":"Sicilian Defense: Czerniak Attack, Queen Fianchetto Variation","moves":["e4","c5","b3","b6"],"family":"Sicilian Defense","volume":"B","variation":"Czerniak Attack, Queen Fianchetto Variation"}]},"meta":{"timestamp":"2026-05-31T09:34:55.043Z","request_id":"4c33b6b6-b755-445a-b30a-23a2b75b1fd7"},"status":"ok","message":"Openings searched","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Totals & ECO volumes","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The Encyclopaedia of Chess Openings (ECO). Search by name/eco/volume, list by ECO code, identify an opening from a move sequence (/v1/identify?moves=1. e4 c5), or get a random opening.","total":3161,"fields":["eco","name","family","variation","pgn","moves","ply","volume"],"source":"lichess-org/chess-openings (ECO)","volumes":{"A":"Flank openings","B":"Semi-Open Games (except the French)","C":"Open Games & the French","D":"Closed & Semi-Closed Games","E":"Indian Defences"},"by_volume":{"A":672,"B":674,"C":1089,"D":458,"E":268},"eco_codes":464},"meta":{"timestamp":"2026-05-31T09:34:55.117Z","request_id":"7cf52043-eb6d-4e49-8e99-457e23574854"},"status":"ok","message":"Meta retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":3600,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":430,"monthly_call_quota":49500,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1250,"monthly_call_quota":243000,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":3380,"monthly_call_quota":1205000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/chessopenings-api"}