Skip to content
AIRVA
Get a quote

The Cooling Planner, as an API

The same deterministic engine behind the Cooling Planner, callable from your app or your AI agent. Send structured answers about a UK home; get the recommended system, indicative costs, the reasons, the alternatives, what an installer must confirm, and which single change would alter the verdict. No personal data in or out. Free, rate-limited.

Endpoints

POST/api/recommendAnswers in, recommendation out.
GET/api/recommend/questionsThe questions, options, plain-English copy, the JSON Schema for Answers, and the pre-computed common situations.
GET/openapi.jsonOpenAPI 3.1 document.
POST/api/mcpMCP server (Streamable HTTP, stateless). Tools: list_questions, recommend, common_situations.
GET/llms.txtPlain-text index of the site for language models.

Quick start

a rented flat where nothing permanent can be installed — the answers below are the situation on this page: A rented flat where nothing permanent can be installed.

curl -X POST https://www.airva.co.uk/api/recommend \
  -H 'content-type: application/json' \
  -d '{"scope":"one_room","rooms":[{"type":"bedroom","sizeBand":"medium"}],"installPreference":"either","permanentChanges":"no","outdoorUnit":"no","windowType":"unknown","usage":"summer","heating":"no","costStance":"under_1500","priority":"overall"}'
Request body, formatted
{
  "scope": "one_room",
  "rooms": [
    {
      "type": "bedroom",
      "sizeBand": "medium"
    }
  ],
  "installPreference": "either",
  "permanentChanges": "no",
  "outdoorUnit": "no",
  "windowType": "unknown",
  "usage": "summer",
  "heating": "no",
  "costStance": "under_1500",
  "priority": "overall"
}
Response (live: computed from the engine at build time)
{
  "engineVersion": "2.0",
  "input": {
    "scope": "one_room",
    "rooms": [
      {
        "type": "bedroom",
        "sizeBand": "medium"
      }
    ],
    "installPreference": "either",
    "permanentChanges": "no",
    "outdoorUnit": "no",
    "windowType": "unknown",
    "usage": "summer",
    "heating": "no",
    "costStance": "under_1500",
    "priority": "overall"
  },
  "mode": "single_room",
  "summary": "This looks like the best fit because you're cooling one room, a separate outdoor unit isn't an option and you can't make permanent changes.",
  "primary": {
    "id": "window_ac",
    "name": "Window air conditioner",
    "subtitle": "Self-contained unit fitted in a suitable window opening",
    "guideUrl": "https://www.airva.co.uk/home-air-conditioning/without-outdoor-unit",
    "cost": {
      "low": 300,
      "high": 900,
      "currency": "GBP",
      "kind": "purchase",
      "basis": "Airva's own market estimate for a decent unit; not a quotation."
    },
    "reasons": [
      {
        "code": "ONE_ROOM",
        "text": "Well suited to a single room"
      },
      {
        "code": "NO_OUTDOOR_UNIT",
        "text": "No separate outdoor condenser"
      },
      {
        "code": "NO_PERMANENT_CHANGES",
        "text": "No drilling or permanent changes"
      },
      {
        "code": "BUDGET_UNDER_1500",
        "text": "Fits a budget under about £1,500"
      }
    ]
  },
  "confidence": {
    "level": "high",
    "reason": "A clear lead over the next option — the answer you weren't sure of doesn't change it."
  },
  "alternatives": [
    {
      "id": "portable_ac",
      "name": "Portable air conditioner",
      "verdict": "good_alternative",
      "cost": {
        "low": 250,
        "high": 700,
        "currency": "GBP",
        "kind": "purchase",
        "basis": "Airva's own market estimate for a decent unit; not a quotation."
      },
      "differences": [
        "Louder indoors",
        "Dearer to run",
        "Less building work"
      ]
    }
  ],
  "ruledOut": [
    {
      "id": "monobloc_ac",
      "name": "Fixed monobloc air conditioner",
      "reason": "it needs permanent changes to the property"
    },
    {
      "id": "single_split",
      "name": "Single-split air-to-air heat pump",
      "reason": "it needs permanent changes to the property"
    },
    {
      "id": "multi_split",
      "name": "Multi-split air-to-air heat pump",
      "reason": "it needs permanent changes to the property"
    },
    {
      "id": "ducted",
      "name": "Ducted air conditioning",
      "reason": "it needs permanent changes to the property"
    }
  ],
  "checksRequired": [
    {
      "code": "WINDOW_COMPATIBILITY",
      "text": "Whether your window suits a window unit"
    }
  ],
  "notes": [],
  "whatWouldChange": [],
  "links": {
    "plan": "https://www.airva.co.uk/cooling-planner?a=eyJzY29wZSI6Im9uZV9yb29tIiwicm9vbXMiOlt7InR5cGUiOiJiZWRyb29tIiwic2l6ZUJhbmQiOiJtZWRpdW0ifV0sImluc3RhbGxQcmVmZXJlbmNlIjoiZWl0aGVyIiwicGVybWFuZW50Q2hhbmdlcyI6Im5vIiwib3V0ZG9vclVuaXQiOiJubyIsIndpbmRvd1R5cGUiOiJ1bmtub3duIiwidXNhZ2UiOiJzdW1tZXIiLCJoZWF0aW5nIjoibm8iLCJjb3N0U3RhbmNlIjoidW5kZXJfMTUwMCIsInByaW9yaXR5Ijoib3ZlcmFsbCJ9&src=%2Fapi%2Frecommend",
    "planner": "https://www.airva.co.uk/cooling-planner",
    "getMatched": "https://www.airva.co.uk/cooling-planner?a=eyJzY29wZSI6Im9uZV9yb29tIiwicm9vbXMiOlt7InR5cGUiOiJiZWRyb29tIiwic2l6ZUJhbmQiOiJtZWRpdW0ifV0sImluc3RhbGxQcmVmZXJlbmNlIjoiZWl0aGVyIiwicGVybWFuZW50Q2hhbmdlcyI6Im5vIiwib3V0ZG9vclVuaXQiOiJubyIsIndpbmRvd1R5cGUiOiJ1bmtub3duIiwidXNhZ2UiOiJzdW1tZXIiLCJoZWF0aW5nIjoibm8iLCJjb3N0U3RhbmNlIjoidW5kZXJfMTUwMCIsInByaW9yaXR5Ijoib3ZlcmFsbCJ9&src=%2Fapi%2Frecommend#planner-next-step",
    "commonSituations": "https://www.airva.co.uk/cooling-planner/for"
  },
  "disclaimer": "An initial guide, not a technical system design or a formal quotation. Costs are indicative. An installer needs to confirm sizing and siting."
}

MCP server

A remote Model Context Protocol server at https://www.airva.co.uk/api/mcp (Streamable HTTP, stateless, no authentication). Add it as a custom connector in Claude, as an app or connector in ChatGPT, or in any MCP client. Three tools:

  • list_questions — what to ask, with options and why each matters, so the agent can hold the conversation itself.
  • recommend — the answers in, the recommendation out, with a one-paragraph plain-English summary the agent can relay.
  • common_situations — the pre-computed situations, for a quick match without asking every question.
curl -X POST https://www.airva.co.uk/api/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The Answers object

Every field is an enum; the full JSON Schema is in /api/recommend/questions. The essentials:

scopeone_room · few_rooms · whole_home
roomsup to 3 of { type, sizeBand }: bedroom, living_room, kitchen_open_plan, home_office, loft, conservatory, other × small, medium, large, very_large, unknown
installPreferencefixed · removable · either (default). 'removable' means the two capability questions were not asked: send 'unknown' for both.
permanentChangesyes · permission · no · unknown
outdoorUnityes · probably · no · unknown
windowTypevertical_sash · sliding · casement · tilt_turn · other · unknown (optional)
usageoccasional · summer · frequent · unknown (optional)
heatingyes · nice_to_have · no (optional)
costStanceunder_500 · under_1500 · open_to_fixed · unknown (optional)
extrasclean_air · humidity · quiet_night · app_control · discreet (optional, array)
priorityoverall (default) · quiet · upfront_cost · running_cost · minimal_work · external_appearance
wholeHome{ replaceHeating: yes|no|unsure, majorBuildingWork: yes|no|maybe } — whole_home only

Terms of use

  • Free for any use, including commercial, while this page says so. Rate-limited per IP; ask us if you need more.
  • Show the disclaimer field to end users wherever you show the recommendation. It is an initial guide, not a system design or a quotation.
  • Cost figures carry their basis. Installed systems come from our versioned estimator; portable and window units are our own market estimate. Present them as such.
  • Attribute the recommendation to Airva and link to the links.plan URL, which opens the same plan in the planner with every answer intact.
  • Send no personal data. The endpoints take none and store none beyond a hashed IP for rate limiting.
  • The engine is versioned (engineVersion). Weights can change between versions; a response is not a promise.

Questions or higher limits: contact us.