apyhub
Back
▣ MODEL KIT

Go Position Analysis API

What it does

Go Position Analysis evaluates a single Go position with the KataGo engine. You send the moves played so far (plus any setup stones), the ruleset, komi and board size — anything from 2×2 to 19×19 — and get back ranked candidate moves, the expected line of play after each, Black's win probability and expected score lead, and optionally a point-by-point ownership map.

It has one endpoint, Analyze Go Position. Its query.moves and query.rules describe the game, query.maxVisits (16–1,000) trades speed for strength, and the include… flags add ownership maps, their uncertainty, raw policy probabilities and visit counts along each line. Win rates and scores are always from Black's side. Capacity is shared: 10 requests per minute and 10,000 per day across all buyers, with cold starts of up to 40 seconds.

Go Position Analysis is a good fit when you need engine-strength move suggestions or a position evaluation inside a Go app, a game-review tool, a teaching site or a bot — without running a GPU and KataGo yourself.

POST
Analyze Go Position
https://api.eu.apyhub.com/chensichengmalu/analyze-go-position

QUICKSTART

GUIDE

Quickstart

curl -X POST "https://api.eu.apyhub.com/chensichengmalu/analyze-go-position" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": {"id": "position-001", "moves": [["B", "D4"], ["W", "Q16"]], "initialStones": [], "initialPlayer": "B", "rules": "chinese", "komi": 7.5, "boardXSize": 19, "boardYSize": 19, "maxVisits": 128}}'

What you'll get back

A real response to the request above, with moveInfos cut to the top 2 of 25 candidates:

{
  "id": "a67a2c30-e522-4786-b9ae-0f256530e8d9",
  "results": [
    {
      "id": "position-001",
      "isDuringSearch": false,
      "moveInfos": [
        {
          "edgeVisits": 23,
          "edgeWeight": 68.7274098,
          "lcb": 0.36006499,
          "move": "Q4",
          "order": 0,
          "playSelectionValue": 87.1032681,
          "prior": 0.148080483,
          "pv": [
            "Q4",
            "D16",
            "C14",
            "R3",
            "R4",
            "Q3",
            "P4",
            "O2",
            "O17"
          ],
          "scoreLead": -0.829977172,
          "scoreMean": -0.829977172,
          "scoreSelfplay": -1.47433381,
          "scoreStdev": 14.3836344,
          "utility": -0.271389663,
          "utilityLcb": -0.287650735,
          "visits": 23,
          "weight": 68.7274098,
          "winrate": 0.365872516
        },
        {
          "edgeVisits": 23,
          "edgeWeight": 68.7274098,
          "isSymmetryOf": "Q4",
          "lcb": 0.36006499,
          "move": "D16",
          "order": 1,
          "playSelectionValue": 87.1032681,
          "prior": 0.148080483,
          "pv": [
            "D16",
            "Q4",
            "O3",
            "C17",
            "D17",
            "C16",
            "D15",
            "B14",
            "R14"
          ],
          "scoreLead": -0.829977172,
          "scoreMean": -0.829977172,
          "scoreSelfplay": -1.47433381,
          "scoreStdev": 14.3836344,
          "utility": -0.271389663,
          "utilityLcb": -0.287650735,
          "visits": 23,
          "weight": 68.7274098,
          "winrate": 0.365872516
        }
      ],
      "rootInfo": {
        "currentPlayer": "B",
        "rawLead": -0.940142393,
        "rawNoResultProb": 0.00191160478,
        "rawScoreSelfplay": -1.77044725,
        "rawScoreSelfplayStdev": 15.7489616,
        "rawStScoreError": 0.430892259,
        "rawStWrError": 0.0235168915,
        "rawVarTimeLeft": 55.916153,
        "rawWinrate": 0.359518915,
        "scoreLead": -0.837885744,
        "scoreSelfplay": -1.51583622,
        "scoreStdev": 14.2091842,
        "symHash": "3862C0A608F2A84E883950EFC2AF0DC8",
        "thisHash": "61716259BD714312DC16933A804034BD",
        "utility": -0.274976737,
        "visits": 135,
        "weight": 408.61688680863534,
        "winrate": 0.364717179
      },
      "turnNumber": 2
    }
  ],
  "usage": {
    "visits": 135,
    "queuedMs": 66,
    "executionMs": 2,
    "preset": "fast",
    "model": "kata1-tf2-b10c384-s2941M-d5872M",
    "gpuName": "NVIDIA L20"
  }
}
TRY ITLIVE · 400 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
The position to analyse, wrapped in a `query` object.
query*
Caller-provided printable query identifier.
moves*
Move history in order; pass is allowed.
Scoring and ko ruleset — chinese, japanese, korean, aga (American Go Association), tromp-taylor, new-zealand, chinese-ogs (Chinese as played on OGS), stone-scoring, ancient-territory, bga (British Go Association), aga-button (AGA with the pass button).
Requested search target; actual visits can slightly exceed this with parallel search and are reported exactly in usage.visits.
Board width in points, 2–19.
Board height in points, 2–19.
White compensation, integer or half-integer.
Return policy probabilities.
Color to move before moves; set W for a handicap start when appropriate.

About this endpoint

What it does

Analyses one Go position with the KataGo engine and returns the best candidate moves, the expected line of play after each, Black's win probability and score lead, and — on request — a predicted ownership map of the board. Send the move history (and any setup stones) for a board of 2×2 up to 19×19; win rates and scores are always reported from Black's side, even when White is to move.

Shared capacity is 10 requests per minute, 10,000 per UTC day and 3 at once across all buyers. A cold start can take 20–40 seconds, so use a 90-second client timeout and honour Retry-After on 429. Illegal input (bad coordinates, occupied points, ko or suicide where the rules forbid it) returns 400; a body over 64 KiB returns 413.

Request Body

FieldTypeRequiredDescription
queryobjectYesWrapper for the position; every field below goes inside it.
query.idstringYesYour own label for this request, 1–128 printable characters; returned as results[].id.
query.movesarrayYesMoves played so far, in order, up to 2,000. Each is [colour, coordinate]: colour B (Black) or W (White); coordinate in GTP form — column A–T skipping I, then row from 1 at the bottom (e.g. D4) — or pass.
query.rulesstringYesScoring and ko ruleset — chinese, japanese, korean, aga (American Go Association), tromp-taylor, new-zealand, chinese-ogs (Chinese as played on OGS), stone-scoring, ancient-territory, bga (British Go Association), aga-button (AGA with the pass button).
query.boardXSizeintegerYesBoard width in points, 2–19.
query.boardYSizeintegerYesBoard height in points, 2–19.
query.maxVisitsintegerYesSearch effort, 16–1,000 visits. Higher is stronger and slower; the actual count can slightly exceed it and is returned in usage.visits.
query.kominumberNoPoints given to White, −400 to 400 in steps of 0.5. Default 7.5.
query.initialStonesarrayNoStones already on the board before moves, up to 361, as [colour, coordinate] pairs. No pass, no repeated points. Default [].
query.initialPlayerstringNoWho moves first in moves — B (Black) or W (White, e.g. after handicap stones). Default B.
query.includeOwnershipbooleanNoReturn results[].ownership. Default false.
query.includeOwnershipStdevbooleanNoReturn results[].ownershipStdev. Default false.
query.includeMovesOwnershipbooleanNoReturn ownership on every candidate move. Default false.
query.includeMovesOwnershipStdevbooleanNoReturn ownershipStdev on every candidate move. Default false.
query.includePolicybooleanNoReturn results[].policy. Default false.
query.includePVVisitsbooleanNoReturn pvVisits and pvEdgeVisits on every candidate move. Default false.

Response

A JSON object holding one result for your position, with candidate moves ranked best first and the resources the search used.

FieldTypeDescription
idstringJob identifier ApyHub's upstream assigns to this analysis (a UUID); differs on every call.
resultsarrayAnalysis results — one object for the position you sent.
results[].idstringYour query.id, echoed back unchanged.
results[].isDuringSearchbooleanAlways false here: the result is the finished search, not a partial update.
results[].turnNumberintegerNumber of moves from query.moves that were played before the analysed position.
results[].rootInfoobjectEvaluation of the analysed position itself.
results[].rootInfo.currentPlayerstringColour to move in the analysed position — B (Black) or W (White).
results[].rootInfo.visitsintegerSearch visits actually completed on the position.
results[].rootInfo.winratenumberProbability Black wins, 0 to 1 — always from Black's side, even when White is to move.
results[].rootInfo.scoreLeadnumberExpected Black lead in points (komi included); negative means White leads.
results[].rootInfo.scoreSelfplaynumberExpected final Black margin in points if the engine played the game out against itself; negative favours White.
results[].rootInfo.scoreStdevnumberStandard deviation of the expected score, in points — how uncertain the score estimate is.
results[].rootInfo.utilitynumberEngine's combined win/score value used to rank positions, from Black's side; higher is better for Black.
results[].rootInfo.weightnumberTotal search weight behind the evaluation (visits adjusted for confidence).
results[].rootInfo.rawWinratenumberNeural network's Black win probability before any search, 0 to 1.
results[].rootInfo.rawLeadnumberNeural network's expected Black lead in points before any search.
results[].rootInfo.rawScoreSelfplaynumberNeural network's expected self-play Black margin in points before any search.
results[].rootInfo.rawScoreSelfplayStdevnumberStandard deviation of rawScoreSelfplay, in points.
results[].rootInfo.rawNoResultProbnumberNeural network's probability the game ends with no result (for example a triple ko), 0 to 1.
results[].rootInfo.rawStWrErrornumberNeural network's own estimate of its short-term win-rate error.
results[].rootInfo.rawStScoreErrornumberNeural network's own estimate of its short-term score error, in points.
results[].rootInfo.rawVarTimeLeftnumberNeural network's estimate of how much the evaluation can still swing before the game ends.
results[].rootInfo.thisHashstringHex hash identifying this exact position and player to move.
results[].rootInfo.symHashstringHex hash that is the same for this position and all its rotations and reflections.
results[].moveInfosarrayCandidate moves for the player to move, best first.
results[].moveInfos[].movestringCandidate move as a GTP coordinate (column letter A–T without I, then row number, e.g. Q4) or pass.
results[].moveInfos[].orderintegerRank of the candidate, 0 = best.
results[].moveInfos[].isSymmetryOfstringPresent only when this move is a mirror/rotation of a move listed earlier; names that move. Its numbers are copied from it.
results[].moveInfos[].visitsintegerSearch visits spent on this candidate.
results[].moveInfos[].edgeVisitsintegerVisits the root gave to this move directly; can differ from visits when positions repeat in the tree.
results[].moveInfos[].weightnumberSearch weight behind this candidate's numbers.
results[].moveInfos[].edgeWeightnumberSearch weight the root gave to this move directly.
results[].moveInfos[].winratenumberProbability Black wins after this move, 0 to 1, from Black's side.
results[].moveInfos[].lcbnumberLower confidence bound of winrate (Black's side) — a cautious win-rate estimate.
results[].moveInfos[].scoreLeadnumberExpected Black lead in points after this move; negative means White leads.
results[].moveInfos[].scoreMeannumberSame value as scoreLead, kept for older clients.
results[].moveInfos[].scoreSelfplaynumberExpected final Black margin in points after this move if the engine played itself out.
results[].moveInfos[].scoreStdevnumberStandard deviation of the expected score after this move, in points.
results[].moveInfos[].utilitynumberEngine's combined win/score value for this move, from Black's side.
results[].moveInfos[].utilityLcbnumberLower confidence bound of utility.
results[].moveInfos[].priornumberNeural network's probability, before search, that this is the best move, 0 to 1.
results[].moveInfos[].playSelectionValuenumberScore the engine ranks candidates by; higher is preferred.
results[].moveInfos[].pvarrayPrincipal variation: the expected best line of play starting with this move, as GTP coordinates.
results[].moveInfos[].pvVisitsarrayOnly with includePVVisits: search visits behind each move of pv, same order.
results[].moveInfos[].pvEdgeVisitsarrayOnly with includePVVisits: direct visits given to each move of pv, same order.
results[].moveInfos[].ownershiparrayOnly with includeMovesOwnership: predicted final ownership after this move — 361 values (one per board point, row-major from the top-left, A19 → T1 on 19×19), each −1 (White owns) to +1 (Black owns).
results[].moveInfos[].ownershipStdevarrayOnly with includeMovesOwnershipStdev: uncertainty of each ownership value, 0 to 1, same order.
results[].ownershiparrayOnly with includeOwnership: predicted final ownership of the position — 361 values (one per board point, row-major from the top-left, A19 → T1 on 19×19), each −1 (White owns) to +1 (Black owns).
results[].ownershipStdevarrayOnly with includeOwnershipStdev: uncertainty of each ownership value, 0 to 1, same order.
results[].policyarrayOnly with includePolicy: neural network move probabilities — one per board point (row-major from the top-left) then one for pass (362 on 19×19); -1 marks an illegal point.
usageobjectWhat the call consumed.
usage.visitsintegerSearch visits actually completed; can slightly exceed maxVisits because the search runs in parallel.
usage.queuedMsnumberTime the request waited for an engine, in milliseconds.
usage.executionMsnumberEngine compute time in milliseconds, excluding HTTP transfer and cold starts.
usage.presetstringAnalysis profile the engine ran (e.g. fast).
usage.modelstringKataGo neural network that produced the analysis (e.g. kata1-tf2-b10c384-s2941M-d5872M).
usage.gpuNamestringGPU model the analysis ran on.
▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.