Skip to content
pokemontcgapi.com
sign in
Documentation

Grade known centering ratios

Maximum grades from known centering ratios for PSA, BGS, CGC and SGC.

POST/v1/centering/grade1 credits; verified Free trial: 5 measure and 5 confirm calls, independently. Developer excluded.growth plan

Cache-Control: private, no-store

Objects returned

No key yet? One call gets you one: POST /v1/accounts/free with an Idempotency-Key header and your email address returns a working key in the response. Keep the original Idempotency-Key and body for response replay for up to 24 hours, under the conditions in the quickstart. The trial is 800 credits over 30 days once the address is confirmed, no card; paid plans start at 29 € a month. See the quickstart and the pricing.

Calculate maximum grades from known ratios, without uploading a photo. Read incomplete, missing_faces and each face’s missing_axes. Normalizations disclose fractions, array pairs and alternate argument forms. Per-house source_status and standard_status distinguish official, interpreted and approximate thresholds. An unconstrained face may have a null maximum_grade.

Growth and higher; Developer is excluded. A verified Free trial includes 5 measure and 5 confirm calls, with independent counters. Grade and standards are available during the verified trial without separate call counters. All calls still consume credits. Requires vision:read. See the two-step centering guide.

Always display: ceiling from centering alone, not a prediction of the final grade. Results are client-confirmed when a person checks the lines; never describe them as verified or certified.

Validation uses 400 INVALID_PARAMETER: service validation includes details.service_code and details.param; upload validation may carry only details.param. Busy, failed or timed-out processing returns 503 PROVIDER_UNAVAILABLE with Retry-After: 2. A deployment without centering returns 503 FEATURE_NOT_CONFIGURED. Ineligible plans, unverified Free accounts or exhausted measure/confirm trial counters return 403 PLAN_REQUIRED; follow details.next_step when present. Errors refund credits and trial reservations.

Body fields

Body fields
NameTypeDefaultDescription
front_lrnumber | string | array—Known front lr ratio: 55, 0.55, 55/45 or [55,45]. Supply at least one axis. Missing axes and faces can lower the ceiling; never infer them. Numeric 1 is ambiguous and rejected.
front_tbnumber | string | array—Known front tb ratio: 55, 0.55, 55/45 or [55,45]. Supply at least one axis. Missing axes and faces can lower the ceiling; never infer them. Numeric 1 is ambiguous and rejected.
back_lrnumber | string | array—Known back lr ratio: 55, 0.55, 55/45 or [55,45]. Supply at least one axis. Missing axes and faces can lower the ceiling; never infer them. Numeric 1 is ambiguous and rejected.
back_tbnumber | string | array—Known back tb ratio: 55, 0.55, 55/45 or [55,45]. Supply at least one axis. Missing axes and faces can lower the ceiling; never infer them. Numeric 1 is ambiguous and rejected.
frontobject—Alternative nested {lr,tb}; do not duplicate corresponding flat fields.
backobject—Alternative nested {lr,tb}; do not duplicate corresponding flat fields.
houseenum—Optional PSA, BGS, CGC or SGC; default all four. Case and outer whitespace accepted.

Example request

curl -s "https://api.pokemontcgapi.com/v1/centering/grade" -H "X-Api-Key: $PTCG_API_KEY" -H "Content-Type: application/json" -d '{"front_lr":55,"front_tb":52,"house":"PSA"}'

Example response

200 OK · Cache-Control: private, no-store

response.json
{
  "data": {
    "front": {
      "ratios": {
        "lr": 55,
        "tb": 52
      },
      "missing_axes": [],
      "ceilings": {
        "PSA": {
          "maximum_grade": 10,
          "label": "GEM MT",
          "rank": 100,
          "limiting_face": "front",
          "limiting_axis": "lr",
          "distance_to_next": null,
          "next_grade": null,
          "next_label": null,
          "borderline": false,
          "unconstrained": false,
          "source_status": "official",
          "standard_status": "official",
          "source": "https://www.psacard.com/gradingstandards",
          "sources": [
            "https://www.psacard.com/gradingstandards"
          ],
          "reviewed_at": "2026-10-01",
          "verification": "retrieved"
        }
      }
    },
    "back": null,
    "combined": {
      "PSA": {
        "maximum_grade": 10,
        "label": "GEM MT",
        "rank": 100,
        "limiting_face": "front",
        "limiting_axis": "lr",
        "distance_to_next": null,
        "next_grade": null,
        "next_label": null,
        "borderline": false,
        "unconstrained": false,
        "source_status": "official",
        "standard_status": "official",
        "source": "https://www.psacard.com/gradingstandards",
        "sources": [
          "https://www.psacard.com/gradingstandards"
        ],
        "reviewed_at": "2026-10-01",
        "verification": "retrieved"
      }
    },
    "normalizations": [],
    "incomplete": true,
    "missing_faces": [
      "back"
    ],
    "summary": "PSA: 10 GEM MT. These ceilings use only the supplied ratios; missing axes or the other face can lower them. This is a ceiling from centering alone, not a prediction of the final grade.",
    "disclaimer": "This is a ceiling from centering alone, not a prediction of the final grade."
  },
  "meta": {
    "elapsed_ms": 0,
    "engine_version": "1.0.0"
  }
}

Errors

Every error body carries error.code, error.message and error.request_id. Switch on the code, never on the message.

Errors returned by this endpoint
StatusCodeWhen
401MISSING_API_KEYNo X-Api-Key header and no bearer token on a route that requires one.
INSUFFICIENT_SCOPEINSUFFICIENT_SCOPE—
403PLAN_REQUIREDThe feature is outside the plan (movers require Growth; photo recognition has 5 calls after Free email confirmation, then requires Growth), or the account subscription is canceled or suspended. Centering requires Growth or higher; Developer is excluded. After email confirmation the trial includes 5 measure and 5 confirm calls independently; grade and standards use trial credits without separate call counters. Before email confirmation, the message starts with “Confirm your email…”. Follow details.next_step when present.
400INVALID_PARAMETERA query parameter has the wrong type or an unsupported value — a non-integer limit, an unknown lang, an unknown region, a sort key that is not sortable.
PROVIDER_UNAVAILABLEPROVIDER_UNAVAILABLE—
503FEATURE_NOT_CONFIGUREDThe endpoint exists but its optional backend is not configured in this deployment.
415UNSUPPORTED_MEDIA_TYPEThe Content-Type is not one this route accepts.
413PAYLOAD_TOO_LARGEThe request body is larger than the server accepts.
429QUOTA_EXCEEDEDTrial credits, monthly credits or the daily cap are exhausted, and details says which: daily_cap with retry_after_s is the trial daily cap, which resets at midnight UTC; renews: true with resets_at is the monthly quota of a paid plan; renews: false is the trial allowance, which never comes back. details.next_step carries the plan, prices and owner action, or email verification when it unlocks the full trial.
403TRIAL_EXPIREDThe trial has ended: the account is on the trial and its 30 days from signup are over, and this route costs credits. details.trial_expired_at is the date, details.trial_days the length, and details.next_step the owner handoff. Zero-cost routes — /v1/me, /v1/me/usage, the key routes and /v1/billing/checkout — still answer.

The full taxonomy, with what to do about each code, is on the errors page.

view this page as markdown