---
title: "Resolve — plain-text description → ranked factor keys + confidence"
method: POST
path: "/v1/calculate/resolve"
tags: ["Calculate"]
---

# Resolve — plain-text description → ranked factor keys + confidence

`POST /v1/calculate/resolve`

## Request

- Base URL: `https://api.greencalculus.com`
- URL: `https://api.greencalculus.com/v1/calculate/resolve`
- Auth: HTTP bearer

## Request body

- object
  - `description` string, required: Plain-language description of the factor you need.
  - `section` string: Optional. Restrict candidates to one MB section.
  - `limit` integer: Optional. Number of ranked candidates to return.

## Response `200`

Ranked candidate factor keys with confidence scores. Each match carries country_iso3 and geo_match ("exact" | "global" | "proxy"); a "proxy" match is a factor from a different country than the one asked for, and its confidence is discounted accordingly.

- Resolve: Plain-description → candidate factors, ranked. Deliberately NOT a single answer: every live defect this endpoint produced was a CONFIDENT wrong answer, so each match carries a confidence, a label and the reasons behind it.
  - `methodology` string
  - `query` string: The description as received.
  - `country_iso3` string, nullable: The country parsed out of the description, or null.
  - `tokens` string[]: How the description was tokenised — shown so a bad parse is visible rather than mysterious.
  - `count` integer
  - `matches` object[]
    - `key` string
    - `name` string, nullable
    - `section` string, nullable
    - `value` number, nullable
    - `unit` string, nullable
    - `source_id` string, nullable
    - `country_iso3` string, nullable
    - `geo_match` 'exact' | 'global' | 'proxy': "proxy" is a factor from a DIFFERENT country than the one asked for; its confidence is discounted accordingly.
    - `confidence` number
    - `matched_on` string[]: Which tokens actually matched.
    - `scope` object: GHG Protocol placement of this row. THIS IS THE FIELD THAT MAKES A RANKED LIST DECIDABLE: "UK grid electricity" returns four exact-country rows spanning 0.11507 to 0.28064, and `ghg_protocol` plus `basis` are what tell them apart — two are scope2 (location-based and residual mix, both wanted for dual reporting) and two are outside_scopes (a lifecycle intensity and a biogenic memo) which must never enter a Scope 2 total.
      - `ghg_protocol` string, nullable
      - `category` string, nullable
    - `basis` string, nullable: What the publisher measured — the boundary. Distinguishes same-named rows that differ only in method.
    - `label` 'accept' | 'review': Set to "review" on low confidence, a thin match, a proxy geography, a demoted row, or an `outside_scopes` row returned ALONGSIDE an in-scope one (a memo figure standing next to the inventory figure it would be mistaken for). A set that is entirely outside_scopes — a product-footprint or CBAM query — is NOT demoted, because there is nothing there to confuse it with. Treat "review" as needing a human: a bare float cannot warn anyone.
    - `why` string[]: The reasons behind the label, in plain language.
  - `absence` object, nullable: Present when nothing matched AND we hold a reasoned absence record explaining why — including the case where we DO hold it under another name.
  - `note` string, nullable
  - `meta` object

## Other responses

- `400`: Missing "description"
- `401`: Missing/invalid key

---

[API](https://skmtc.dev/greencalculus/apis/greencalculus-api.md) · [All operations](https://skmtc.dev/greencalculus/apis/greencalculus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greencalculus/apis/greencalculus-api/revisions/2f742325958c?raw)