Commerce for Agents

Compares German electricity and gas tariffs with live market data for a postal code and an annual consumption, and returns one page of the ranked market: prices with and without bonus, monthly average, savings against the local default supplier (Grundversorgung) or the user's current contract, contract terms, price guarantee, eco status and customer ratings. Covers tariff comparison only, not general energy questions. Prices come live from the market data and can change at any time. Keywords: Stromvergleich, Gasvergleich, Stromtarif, Gastarif, Stromanbieter wechseln, Gasanbieter wechseln, Ökostrom, Strompreise, Energiekosten senken, electricity tariff, gas tariff, switch energy provider, Germany. Inputs: postalCode (5 digits) and annualConsumptionKwh. Both come from the user: the ranking is only valid for the household's actual consumption, which is printed on the last bill, and the tool has no default for it. The typical values by household size in the parameter description help a user who does not know the figure; a comparison run on a household size alone is approximate. energyType selects gas; electricity is the default. Without filters the result covers the whole market. An energy bill contains every input: postal code, annual consumption, and the reference for the savings comparison, which is the future monthly payment (Abschlag) if the bill states one, otherwise the Arbeitspreis and Grundpreis lines (see the current* parameters). The bill total belongs to the past period and may include a one-time bonus, so it is not a reference. The bill's provider, customer number and meter number are the fields the booking form asks for later. Each offer carries its complete data (prices, bonuses, contract terms, flags such as dynamic or eco, ratings, remarks); tariff-details adds the cost breakdown, energy mix and provider details. Only offers with an `eco` object are eco tariffs. Their `eco.statement` and `eco.proof` are legally required wording (EU EmpCo, Directive 2024/825): quote both verbatim when describing a green tariff. Offers without `eco` are not green, eco, renewable or climate-neutral. The ranking method, bonus handling, price guarantees and eco labels are explained at https://commerceforagents.com/comparison-basis. The response states totalResults and how to reach the rest of the ranking (page, providers, filters). Dynamic (spot-price) tariffs are included only with includeDynamicTariffs. The result renders as tariff cards with filters (eco, contract length, price guarantee, bonus handling, providers) below the message, so the list does not need repeating in text. Each offer has a `ref`: tariff-details shows its full conditions, and start-booking opens the booking form in which the user enters the contract data, IBAN and consent. `language` sets the language of the cards and their buttons.

{
  "type": "object",
  "properties": {
    "energyType": {
      "type": "string",
      "enum": [
        "electricity",
        "gas"
      ],
      "description": "Which energy contract to compare: \"electricity\" (Strom) or \"gas\". Default: \"electricity\"."
    },
    "postalCode": {
      "type": "string",
      "pattern": "^\\d{5}$",
      "description": "German postal code (Postleitzahl) — 5 digits, e.g. \"10115\" for Berlin."
    },
    "annualConsumptionKwh": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 1000000,
      "description": "The household's actual annual consumption in kWh, from the user or their last bill; no default. The ranking depends on it. Typical values by household size: electricity ~1500 (1 person), 2500 (2), 3500 (3), 4500 (4+); gas ~9000 (flat), ~20000 (house)."
    },
    "district": {
      "description": "City district (Ortsteil), only needed when the response reports multiple districts for the postal code and the user's district changes the result.",
      "type": "string",
      "maxLength": 100
    },
    "currentAnnualCostEur": {
      "description": "The user's ONGOING yearly cost on their current contract in EUR: current prices, one-time bonuses EXCLUDED. Not the bill total: a new-customer bonus is paid once, so the total of a bonus year understates what they pay next year. Compute Arbeitspreis × kWh / 100 + 12 × Grundpreis (post-increase prices if the bill announces one), or better: pass currentWorkingPriceCtKwh + currentBasePriceEurMonth and let the server compute it. When given, savings are computed against this instead of the default utility tariff.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "currentMonthlyPaymentEur": {
      "description": "The FUTURE monthly payment (Abschlag) stated on the bill for the coming period, e.g. 'Ihr monatlicher Zahlbetrag beträgt zukünftig 159,00 €'. It already reflects price changes after the billing period, which the bill's Arbeitspreis/Grundpreis lines predate. Takes precedence over the price components.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000
    },
    "currentWorkingPriceCtKwh": {
      "description": "Arbeitspreis of the user's current contract in ct/kWh, gross, as printed on the bill (the new price if an increase is announced). Together with currentBasePriceEurMonth the server computes the ongoing yearly cost itself — preferred over currentAnnualCostEur.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 500
    },
    "currentBasePriceEurMonth": {
      "description": "Grundpreis of the user's current contract in EUR per month, gross (a yearly Grundpreis divided by 12).",
      "type": "number",
      "minimum": 0,
      "maximum": 1000
    },
    "currentProvider": {
      "description": "The user's current provider, if known (e.g. from the bill).",
      "type": "string",
      "maxLength": 150
    },
    "currentTariff": {
      "description": "The user's current tariff name, if known (e.g. from the bill).",
      "type": "string",
      "maxLength": 150
    },
    "sortBy": {
      "description": "Market-wide sort: \"price\" (first-year total, default), \"rating\" (customer rating, best first), \"providerName\".",
      "type": "string",
      "enum": [
        "price",
        "rating",
        "providerName"
      ]
    },
    "bonusMode": {
      "description": "How one-time bonuses count in prices and ranking. \"compliant\" (default): only bonuses meeting consumer-protection guidelines; \"all\": every bonus; \"none\": prices without any bonus.",
      "type": "string",
      "enum": [
        "compliant",
        "all",
        "none"
      ]
    },
    "greenOnly": {
      "description": "Only eco tariffs (EU EmpCo definition): electricity from 100% renewable energy proven by guarantees of origin; gas with a declared biogas/hydrogen share. CO2-compensated (\"Klimagas\", \"klimaneutral\") tariffs are NOT eco. Default: false.",
      "type": "boolean"
    },
    "includeDynamicTariffs": {
      "description": "Include dynamic (spot-price) tariffs whose first-year price is only a forecast. Default: false, since most German households book fixed-price tariffs.",
      "type": "boolean"
    },
    "contractMonthsMax": {
      "description": "Maximum initial contract duration in months (1, 3, 6, 12 or 24). Default: no limit.",
      "anyOf": [
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 3
        },
        {
          "type": "number",
          "const": 6
        },
        {
          "type": "number",
          "const": 12
        },
        {
          "type": "number",
          "const": 24
        },
        {
          "type": "null"
        }
      ]
    },
    "priceGuaranteeMonthsMin": {
      "description": "Minimum price-guarantee duration in months. null = no filter (default).",
      "anyOf": [
        {
          "type": "number",
          "const": 6
        },
        {
          "type": "number",
          "const": 12
        },
        {
          "type": "number",
          "const": 24
        },
        {
          "type": "null"
        }
      ]
    },
    "cancellationMax": {
      "description": "Maximum cancellation period (Kündigungsfrist). Omit = no filter.",
      "type": "string",
      "enum": [
        "1_month",
        "6_weeks",
        "3_months"
      ]
    },
    "providers": {
      "description": "Only offers from these providers (names, e.g. [\"Vattenfall\", \"E WIE EINFACH\"]). Restricts the ranking to these providers.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100
      }
    },
    "maxTariffsPerProvider": {
      "description": "Tariffs per provider in the ranking. Default 1 (best per provider); 0 = all tariffs of every provider.",
      "type": "integer",
      "minimum": 0,
      "maximum": 5
    },
    "includePrepayment": {
      "description": "Include tariffs requiring prepayment (Vorauskasse). Default: false.",
      "type": "boolean"
    },
    "includeDeposit": {
      "description": "Include tariffs requiring a deposit (Kaution). Default: false.",
      "type": "boolean"
    },
    "includePackageTariffs": {
      "description": "Include kWh-package tariffs (Pakettarife). Default: false.",
      "type": "boolean"
    },
    "regionalOnly": {
      "description": "Only regional providers / local utilities. Default: false.",
      "type": "boolean"
    },
    "goodRatingOnly": {
      "description": "Only providers with good customer ratings (market operator's threshold). Default: false.",
      "type": "boolean"
    },
    "limit": {
      "description": "Tariffs per page. Default: 10, max 20.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "page": {
      "description": "Result page (1-based). The response reports totalResults; request further pages to see more of the ranking.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "language": {
      "description": "Language of the conversation. The widget's texts and its follow-up messages use it; omit only if unsure, then the user's interface locale is used.",
      "type": "string",
      "enum": [
        "de",
        "en"
      ]
    }
  },
  "required": [
    "postalCode",
    "annualConsumptionKwh"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "object",
      "properties": {
        "energyType": {
          "type": "string",
          "enum": [
            "electricity",
            "gas"
          ],
          "description": "Which energy contract to compare: \"electricity\" (Strom) or \"gas\". Default: \"electricity\"."
        },
        "postalCode": {
          "type": "string",
          "pattern": "^\\d{5}$",
          "description": "German postal code (Postleitzahl) — 5 digits, e.g. \"10115\" for Berlin."
        },
        "annualConsumptionKwh": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 1000000,
          "description": "The household's actual annual consumption in kWh, from the user or their last bill; no default. The ranking depends on it. Typical values by household size: electricity ~1500 (1 person), 2500 (2), 3500 (3), 4500 (4+); gas ~9000 (flat), ~20000 (house)."
        },
        "district": {
          "description": "City district (Ortsteil), only needed when the response reports multiple districts for the postal code and the user's district changes the result.",
          "type": "string",
          "maxLength": 100
        },
        "currentAnnualCostEur": {
          "description": "The user's ONGOING yearly cost on their current contract in EUR: current prices, one-time bonuses EXCLUDED. Not the bill total: a new-customer bonus is paid once, so the total of a bonus year understates what they pay next year. Compute Arbeitspreis × kWh / 100 + 12 × Grundpreis (post-increase prices if the bill announces one), or better: pass currentWorkingPriceCtKwh + currentBasePriceEurMonth and let the server compute it. When given, savings are computed against this instead of the default utility tariff.",
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 100000
        },
        "currentMonthlyPaymentEur": {
          "description": "The FUTURE monthly payment (Abschlag) stated on the bill for the coming period, e.g. 'Ihr monatlicher Zahlbetrag beträgt zukünftig 159,00 €'. It already reflects price changes after the billing period, which the bill's Arbeitspreis/Grundpreis lines predate. Takes precedence over the price components.",
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 10000
        },
        "currentWorkingPriceCtKwh": {
          "description": "Arbeitspreis of the user's current contract in ct/kWh, gross, as printed on the bill (the new price if an increase is announced). Together with currentBasePriceEurMonth the server computes the ongoing yearly cost itself — preferred over currentAnnualCostEur.",
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 500
        },
        "currentBasePriceEurMonth": {
          "description": "Grundpreis of the user's current contract in EUR per month, gross (a yearly Grundpreis divided by 12).",
          "type": "number",
          "minimum": 0,
          "maximum": 1000
        },
        "currentProvider": {
          "description": "The user's current provider, if known (e.g. from the bill).",
          "type": "string",
          "maxLength": 150
        },
        "currentTariff": {
          "description": "The user's current tariff name, if known (e.g. from the bill).",
          "type": "string",
          "maxLength": 150
        },
        "sortBy": {
          "description": "Market-wide sort: \"price\" (first-year total, default), \"rating\" (customer rating, best first), \"providerName\".",
          "type": "string",
          "enum": [
            "price",
            "rating",
            "providerName"
          ]
        },
        "bonusMode": {
          "description": "How one-time bonuses count in prices and ranking. \"compliant\" (default): only bonuses meeting consumer-protection guidelines; \"all\": every bonus; \"none\": prices without any bonus.",
          "type": "string",
          "enum": [
            "compliant",
            "all",
            "none"
          ]
        },
        "greenOnly": {
          "description": "Only eco tariffs (EU EmpCo definition): electricity from 100% renewable energy proven by guarantees of origin; gas with a declared biogas/hydrogen share. CO2-compensated (\"Klimagas\", \"klimaneutral\") tariffs are NOT eco. Default: false.",
          "type": "boolean"
        },
        "includeDynamicTariffs": {
          "description": "Include dynamic (spot-price) tariffs whose first-year price is only a forecast. Default: false, since most German households book fixed-price tariffs.",
          "type": "boolean"
        },
        "contractMonthsMax": {
          "description": "Maximum initial contract duration in months (1, 3, 6, 12 or 24). Default: no limit.",
          "anyOf": [
            {
              "type": "number",
              "const": 1
            },
            {
              "type": "number",
              "const": 3
            },
            {
              "type": "number",
              "const": 6
            },
            {
              "type": "number",
              "const": 12
            },
            {
              "type": "number",
              "const": 24
            },
            {
              "type": "null"
            }
          ]
        },
        "priceGuaranteeMonthsMin": {
          "description": "Minimum price-guarantee duration in months. null = no filter (default).",
          "anyOf": [
            {
              "type": "number",
              "const": 6
            },
            {
              "type": "number",
              "const": 12
            },
            {
              "type": "number",
              "const": 24
            },
            {
              "type": "null"
            }
          ]
        },
        "cancellationMax": {
          "description": "Maximum cancellation period (Kündigungsfrist). Omit = no filter.",
          "type": "string",
          "enum": [
            "1_month",
            "6_weeks",
            "3_months"
          ]
        },
        "providers": {
          "description": "Only offers from these providers (names, e.g. [\"Vattenfall\", \"E WIE EINFACH\"]). Restricts the ranking to these providers.",
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 100
          }
        },
        "maxTariffsPerProvider": {
          "description": "Tariffs per provider in the ranking. Default 1 (best per provider); 0 = all tariffs of every provider.",
          "type": "integer",
          "minimum": 0,
          "maximum": 5
        },
        "includePrepayment": {
          "description": "Include tariffs requiring prepayment (Vorauskasse). Default: false.",
          "type": "boolean"
        },
        "includeDeposit": {
          "description": "Include tariffs requiring a deposit (Kaution). Default: false.",
          "type": "boolean"
        },
        "includePackageTariffs": {
          "description": "Include kWh-package tariffs (Pakettarife). Default: false.",
          "type": "boolean"
        },
        "regionalOnly": {
          "description": "Only regional providers / local utilities. Default: false.",
          "type": "boolean"
        },
        "goodRatingOnly": {
          "description": "Only providers with good customer ratings (market operator's threshold). Default: false.",
          "type": "boolean"
        },
        "limit": {
          "description": "Tariffs per page. Default: 10, max 20.",
          "type": "integer",
          "minimum": 1,
          "maximum": 20
        },
        "page": {
          "description": "Result page (1-based). The response reports totalResults; request further pages to see more of the ranking.",
          "type": "integer",
          "minimum": 1,
          "maximum": 20
        },
        "language": {
          "description": "Language of the conversation. The widget's texts and its follow-up messages use it; omit only if unsure, then the user's interface locale is used.",
          "type": "string",
          "enum": [
            "de",
            "en"
          ]
        }
      },
      "required": [
        "postalCode",
        "annualConsumptionKwh"
      ],
      "additionalProperties": false
    },
    "city": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "district": {
          "type": "string"
        },
        "zipcode": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "zipcode"
      ],
      "additionalProperties": false
    },
    "otherDistricts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "totalResults": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "hiddenDynamicTariffs": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "priceSpanEur": {
      "type": "object",
      "properties": {
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        }
      },
      "required": [
        "min",
        "max"
      ],
      "additionalProperties": false
    },
    "coverageNote": {
      "type": "string"
    },
    "referenceTariff": {
      "type": "object",
      "properties": {
        "provider": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "annualTotalEur": {
          "type": "number"
        },
        "workingPriceCtKwh": {
          "type": "number"
        },
        "source": {
          "type": "string",
          "enum": [
            "default",
            "current"
          ]
        },
        "basis": {
          "type": "string",
          "enum": [
            "monthlyPayment",
            "priceComponents",
            "statedAnnualCost"
          ]
        },
        "monthlyPaymentEur": {
          "type": "number"
        }
      },
      "required": [
        "provider",
        "name",
        "annualTotalEur",
        "source"
      ],
      "additionalProperties": false
    },
    "referenceNote": {
      "type": "string"
    },
    "tariffs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ref": {
            "type": "string"
          },
          "tariffId": {
            "type": "string"
          },
          "resultPosition": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "provider": {
            "type": "string"
          },
          "providerId": {
            "type": "string"
          },
          "providerLogoUrl": {
            "type": "string",
            "format": "uri"
          },
          "name": {
            "type": "string"
          },
          "price": {
            "type": "object",
            "properties": {
              "yearlyEur": {
                "type": "number"
              },
              "monthlyAvgEur": {
                "type": "number"
              },
              "yearlyWithoutBonusEur": {
                "type": "number"
              },
              "bonusEur": {
                "type": "number"
              },
              "bonuses": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "amountEur": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "label",
                    "amountEur"
                  ],
                  "additionalProperties": false
                }
              },
              "workingPriceCtKwh": {
                "type": "number"
              },
              "basePriceEurMonth": {
                "type": "number"
              },
              "effectiveCtKwh": {
                "type": "number"
              },
              "savingsVsDefaultEur": {
                "type": "number"
              },
              "savingsVsCurrentEur": {
                "type": "number"
              },
              "paymentMonthsPerYear": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "yearlyEur",
              "monthlyAvgEur",
              "yearlyWithoutBonusEur",
              "bonusEur",
              "bonuses"
            ],
            "additionalProperties": false
          },
          "contract": {
            "type": "object",
            "properties": {
              "durationMonths": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "prolongation": {
                "type": "string"
              },
              "cancellationPeriod": {
                "type": "string"
              },
              "priceGuaranteeMonths": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "priceGuaranteeType": {
                "type": "string"
              },
              "priceGuaranteeUntil": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "flags": {
            "type": "object",
            "properties": {
              "isDynamic": {
                "type": "boolean"
              },
              "isEco": {
                "type": "boolean"
              },
              "isSecureTariff": {
                "type": "boolean"
              },
              "isMostFairTariff": {
                "type": "boolean"
              },
              "imminentPriceChange": {
                "type": "boolean"
              },
              "isLocalUtility": {
                "type": "boolean"
              }
            },
            "required": [
              "isDynamic",
              "isEco",
              "isSecureTariff",
              "isMostFairTariff",
              "imminentPriceChange",
              "isLocalUtility"
            ],
            "additionalProperties": false
          },
          "eco": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "electricity",
                  "gas"
                ]
              },
              "statement": {
                "type": "string",
                "description": "Marker text in the request language. Legally required wording (EmpCo): quote verbatim."
              },
              "proof": {
                "type": "string",
                "description": "Proof text that belongs to the marker (guarantees of origin, or the biogas/hydrogen shares). Legally required wording (EmpCo): quote verbatim."
              },
              "biogasPercent": {
                "type": "number"
              },
              "hydrogenPercent": {
                "type": "number"
              },
              "certificates": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "kind",
              "statement",
              "proof"
            ],
            "additionalProperties": false
          },
          "rating": {
            "type": "object",
            "properties": {
              "stars": {
                "type": "number"
              },
              "reviews": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "wouldSwitchAgainPct": {
                "type": "number"
              },
              "servicePct": {
                "type": "number"
              },
              "pricePct": {
                "type": "number"
              },
              "switchingPct": {
                "type": "number"
              }
            },
            "additionalProperties": false
          },
          "badges": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "remarks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "ref",
          "tariffId",
          "resultPosition",
          "provider",
          "providerId",
          "name",
          "price",
          "contract",
          "flags",
          "rating",
          "badges",
          "remarks"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "query",
    "city",
    "totalResults",
    "page",
    "hiddenDynamicTariffs",
    "coverageNote",
    "tariffs"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Returns the full conditions of one tariff from a compare-tariffs result, identified by its `ref`: price composition, scope of the price guarantee, contract duration, renewal and cancellation terms, deposit, energy-source mix, customer ratings, and for eco tariffs the required eco statement and proof. Texts come in the requested `language`. Keywords: Tarifdetails, Vertragsbedingungen, Preisgarantie, Kündigungsfrist, Vertragslaufzeit, AGB, tariff conditions, contract details.

{
  "type": "object",
  "properties": {
    "language": {
      "description": "Language of the conversation (for the eco statement and proof texts). Default: de.",
      "type": "string",
      "enum": [
        "de",
        "en"
      ]
    },
    "ref": {
      "type": "string",
      "pattern": "^[a-z0-9]+\\.\\d+$",
      "description": "Offer reference from a compare-tariffs result (field `ref`)."
    }
  },
  "required": [
    "ref"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string"
    },
    "provider": {
      "type": "string"
    },
    "tariff": {
      "type": "string"
    },
    "energyType": {
      "type": "string",
      "enum": [
        "electricity",
        "gas"
      ]
    },
    "annualTotalEur": {
      "type": "number"
    },
    "costBreakdown": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "label",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "contract": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "label",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "energySources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "label",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "eco": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "electricity",
            "gas"
          ]
        },
        "statement": {
          "type": "string",
          "description": "Marker text in the request language. Legally required wording (EmpCo): quote verbatim."
        },
        "proof": {
          "type": "string",
          "description": "Proof text that belongs to the marker (guarantees of origin, or the biogas/hydrogen shares). Legally required wording (EmpCo): quote verbatim."
        },
        "biogasPercent": {
          "type": "number"
        },
        "hydrogenPercent": {
          "type": "number"
        },
        "certificates": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "kind",
        "statement",
        "proof"
      ],
      "additionalProperties": false
    },
    "customerRatings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "label",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "remarks": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ref",
    "provider",
    "tariff",
    "energyType",
    "annualTotalEur",
    "costBreakdown",
    "contract"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Opens the booking form for one offer from a comparison, identified by its `ref`; the form renders below the message. Read-only: the call submits, stores and sends nothing, and takes no personal data. In the form the user enters the contract details (page 1), then the IBAN and consent (page 2), and files the request there. Messages such as 'Bitte öffne das Buchungsformular', 'ich möchte diesen Tarif', 'den nehme ich', 'book #2' or 'switch me to this', usually sent by the card's 'Jetzt buchen' button, ask for this form. `language` sets the language of the form. There is no self-service checkout link. Keywords: Buchungsformular, Tarif buchen, wechseln, Wechsel beauftragen, Vertrag abschließen, open booking form, book, switch, sign up.

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z0-9]+\\.\\d+$",
      "description": "Offer reference from a compare-tariffs result (field `ref`). No personal data."
    },
    "language": {
      "description": "Language of the conversation; the booking form uses it. Default: de.",
      "type": "string",
      "enum": [
        "de",
        "en"
      ]
    }
  },
  "required": [
    "ref"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string"
    },
    "provider": {
      "type": "string"
    },
    "tariff": {
      "type": "string"
    },
    "annualTotalEur": {
      "type": "number"
    },
    "monthlyAvgEur": {
      "type": "number"
    },
    "energyType": {
      "type": "string",
      "enum": [
        "electricity",
        "gas"
      ]
    },
    "annualConsumptionKwh": {
      "type": "number"
    },
    "postalCode": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "providerLogoUrl": {
      "type": "string"
    },
    "language": {
      "type": "string",
      "enum": [
        "de",
        "en"
      ]
    },
    "instruction": {
      "type": "string"
    }
  },
  "required": [
    "ref",
    "provider",
    "tariff",
    "annualTotalEur",
    "monthlyAvgEur",
    "energyType",
    "annualConsumptionKwh",
    "postalCode",
    "language",
    "instruction"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Compares and ranks US mobile phone plans, cheapest first, from a curated catalog of carrier and prepaid (MVNO) plans, each price checked on the provider's own page, by 12-month average cost per line, with any promo price shown alongside. The catalog is a selection, not the whole market; each result states how many plans and providers it covers and the oldest price-check date. Inputs: number of lines, and optionally data need, budget per line, prepaid or postpaid, must-have features and preferred network. No address or location is used, so network coverage is not checked; each result carries a coverage note. Keywords: cheapest phone plan, compare cell phone plans, cell phone plan, mobile plan comparison, switch carriers, unlimited data plan, family plan, prepaid vs postpaid.

{
  "type": "object",
  "properties": {
    "lines": {
      "default": 1,
      "description": "Number of phone lines to price.",
      "type": "integer",
      "minimum": 1,
      "maximum": 6
    },
    "data_need": {
      "description": "Minimum data: light ≥2GB, moderate ≥5GB, heavy ≥20GB, unlimited = unlimited plans only.",
      "type": "string",
      "enum": [
        "light",
        "moderate",
        "heavy",
        "unlimited"
      ]
    },
    "budget_per_line": {
      "description": "Max USD/month per line.",
      "type": "number",
      "minimum": 0
    },
    "prepaid_or_postpaid": {
      "description": "Restrict to prepaid or postpaid plans; omit for both.",
      "type": "string",
      "enum": [
        "prepaid",
        "postpaid"
      ]
    },
    "must_haves": {
      "description": "Required features: hotspot, 5g, premium_data (deprioritization-free), unlimited_data.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "hotspot",
          "5g",
          "premium_data",
          "unlimited_data"
        ]
      }
    },
    "preferred_network": {
      "description": "Preferred underlying network, e.g. AT&T, Verizon, T-Mobile.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "plans": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "plan": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "prepaid": {
            "type": "boolean"
          },
          "effectivePricePerLine": {
            "type": "number",
            "description": "12-month average USD per line; the ranking price."
          },
          "steadyStatePricePerLine": {
            "type": "number",
            "description": "Regular USD per line after any promo."
          },
          "promoPricePerLine": {
            "type": "number"
          },
          "promoDurationMonths": {
            "type": "number"
          },
          "billedAnnually": {
            "description": "Paid upfront for a year; price is the per-month equivalent.",
            "type": "boolean"
          },
          "effectiveTotalMonthly": {
            "type": "number"
          },
          "taxesIncluded": {
            "type": "boolean"
          },
          "autopayRequired": {
            "type": "boolean"
          },
          "verifiedDate": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "sourceUrl": {
            "type": "string"
          },
          "offerUrl": {
            "type": "string"
          }
        },
        "required": [
          "rank",
          "id",
          "provider",
          "plan",
          "network",
          "prepaid",
          "effectivePricePerLine",
          "steadyStatePricePerLine",
          "effectiveTotalMonthly",
          "verifiedDate",
          "sourceUrl"
        ],
        "additionalProperties": {}
      }
    },
    "lines": {
      "type": "number"
    },
    "selectionNote": {
      "type": "string",
      "description": "Curated selection of N plans from M providers, not the whole market."
    },
    "catalogPlanCount": {
      "type": "number"
    },
    "catalogProviderCount": {
      "type": "number"
    },
    "oldestVerifiedDate": {
      "description": "Oldest verified_date among the plans shown.",
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "coverageNote": {
      "type": "string"
    },
    "priceNote": {
      "type": "string"
    },
    "source": {
      "type": "string"
    }
  },
  "required": [
    "plans",
    "lines",
    "selectionNote",
    "catalogPlanCount",
    "catalogProviderCount",
    "coverageNote",
    "priceNote",
    "source"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when the user wants a travel eSIM, compares eSIM data plans for a trip abroad, or asks for the cheapest eSIM for a country. Ranks a curated catalog of country eSIM packages (Airalo, Saily, Holafly, Nomad) by USD list price among packages valid for the whole trip with at least the data needed, listing each provider's cheapest package first and then the remaining packages by price, and shows price per GB and per day with a provider link. Destinations: JP, US, GB, FR, IT, ES, TH, MX. Inputs: destination (country code), days, optional data_gb, unlimited and providers. No personal data is used. Keywords: travel eSIM, eSIM for Japan, cheapest eSIM, international data plan, roaming.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "Destination country, ISO 3166-1 alpha-2 (e.g. JP, US, GB, FR, IT, ES, TH, MX)."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "Trip length in days; packages must be valid at least this long."
    },
    "data_gb": {
      "description": "Minimum data needed in GB (default 1). Ignored when unlimited is true.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "unlimited": {
      "description": "true: only unlimited-data packages; false: exclude them; omitted: unlimited packages also qualify.",
      "type": "boolean"
    },
    "providers": {
      "description": "Only these providers, e.g. [\"Airalo\", \"Saily\"].",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "destination",
    "days"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string"
    },
    "days": {
      "type": "number"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "coverage": {
            "type": "string",
            "enum": [
              "country",
              "regional"
            ]
          },
          "dataGb": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "unlimited": {
            "type": "boolean"
          },
          "validityDays": {
            "type": "number"
          },
          "priceUsd": {
            "type": "number",
            "description": "Regular price; the ranking price."
          },
          "salePriceUsd": {
            "description": "Current sale price, end date not stated by the provider; not used for ranking.",
            "type": "number"
          },
          "pricePerGb": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "pricePerDay": {
            "type": "number"
          },
          "sourceUrl": {
            "type": "string"
          },
          "offerUrl": {
            "type": "string"
          },
          "isAffiliateLink": {
            "type": "boolean"
          },
          "verifiedDate": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "offerRef": {
            "description": "Pass to buy-esim to buy this package in chat, where available. Valid 24 hours.",
            "type": "string"
          }
        },
        "required": [
          "rank",
          "id",
          "provider",
          "name",
          "coverage",
          "dataGb",
          "unlimited",
          "validityDays",
          "priceUsd",
          "pricePerGb",
          "pricePerDay",
          "sourceUrl",
          "verifiedDate"
        ],
        "additionalProperties": {}
      }
    },
    "closest": {
      "description": "When nothing qualifies: the largest package that lasts the trip.",
      "type": "object",
      "properties": {
        "rank": {
          "type": "number"
        },
        "id": {
          "type": "string"
        },
        "provider": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "coverage": {
          "type": "string",
          "enum": [
            "country",
            "regional"
          ]
        },
        "dataGb": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "unlimited": {
          "type": "boolean"
        },
        "validityDays": {
          "type": "number"
        },
        "priceUsd": {
          "type": "number",
          "description": "Regular price; the ranking price."
        },
        "salePriceUsd": {
          "description": "Current sale price, end date not stated by the provider; not used for ranking.",
          "type": "number"
        },
        "pricePerGb": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "pricePerDay": {
          "type": "number"
        },
        "sourceUrl": {
          "type": "string"
        },
        "offerUrl": {
          "type": "string"
        },
        "isAffiliateLink": {
          "type": "boolean"
        },
        "verifiedDate": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "offerRef": {
          "description": "Pass to buy-esim to buy this package in chat, where available. Valid 24 hours.",
          "type": "string"
        }
      },
      "required": [
        "rank",
        "id",
        "provider",
        "name",
        "coverage",
        "dataGb",
        "unlimited",
        "validityDays",
        "priceUsd",
        "pricePerGb",
        "pricePerDay",
        "sourceUrl",
        "verifiedDate"
      ],
      "additionalProperties": {}
    },
    "excluded": {
      "type": "object",
      "properties": {
        "stale": {
          "type": "number"
        },
        "noMatch": {
          "type": "number"
        }
      },
      "required": [
        "stale",
        "noMatch"
      ],
      "additionalProperties": false
    },
    "catalogVerifiedOldest": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "disclosure": {
      "type": "string"
    },
    "basis": {
      "type": "string"
    }
  },
  "required": [
    "destination",
    "days",
    "results",
    "excluded",
    "disclosure",
    "basis"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Files a concierge switch request with the complete contract data in one call. Intended for autonomous agents that already hold the user's full profile, IBAN and a standing authorization; in a conversation with a person, start-booking opens a form in which the user enters these data. Commerce for Agents stores the request encrypted and an operator submits the contract application to the provider; the user receives a confirmation email at once and the provider's contract documents later. There is no self-service checkout link. Input: the `ref` of the chosen offer plus the contract data. Postal code and city come from the comparison; previousProvider, previousCustomerNumber and meterNumber are printed on the last energy bill. `consent: true` attests that the user explicitly agreed to (1) Commerce for Agents submitting the contract on their behalf, (2) the SEPA direct-debit mandate for the given IBAN and (3) the privacy policy at commerceforagents.com/privacy, either by an explicit yes in the conversation or by a standing authorization given to the agent. The response contains nextSteps for the user.

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z0-9]+\\.\\d+$",
      "description": "Offer reference from a compare-tariffs result (field `ref`)."
    },
    "language": {
      "description": "Language of the conversation — used for the confirmation email. Default: \"de\".",
      "type": "string",
      "enum": [
        "de",
        "en"
      ]
    },
    "salutation": {
      "type": "string",
      "enum": [
        "herr",
        "frau",
        "divers"
      ],
      "description": "Salutation (Anrede), required by the providers: \"herr\", \"frau\" or \"divers\"."
    },
    "firstName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "First name (Vorname)."
    },
    "lastName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Last name (Nachname)."
    },
    "birthDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date of birth, ISO format YYYY-MM-DD. Energy providers require it for the contract."
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Email address — receives the booking confirmation and provider documents."
    },
    "phone": {
      "description": "Phone number (optional, some providers ask for it).",
      "type": "string",
      "maxLength": 40
    },
    "street": {
      "type": "string",
      "minLength": 1,
      "maxLength": 150,
      "description": "Street of the supply address (Straße)."
    },
    "houseNumber": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "description": "House number (Hausnummer), e.g. \"12a\"."
    },
    "switchType": {
      "type": "string",
      "enum": [
        "switch",
        "relocation"
      ],
      "description": "\"switch\": changing provider at the current address (Anbieterwechsel). \"relocation\": moving in / first contract at this address (Umzug/Neueinzug)."
    },
    "previousProvider": {
      "description": "Current/previous energy provider. Required for switchType \"switch\".",
      "type": "string",
      "maxLength": 150
    },
    "moveInDate": {
      "description": "Move-in date (Umzugsdatum), ISO YYYY-MM-DD. Required for switchType \"relocation\", ignored for a switch.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "previousCustomerNumber": {
      "description": "Customer number at the previous provider (Kundennummer, optional but speeds up the switch).",
      "type": "string",
      "maxLength": 60
    },
    "meterNumber": {
      "description": "Meter number (Zählernummer, optional — printed on the meter or the last bill).",
      "type": "string",
      "maxLength": 60
    },
    "desiredStartDate": {
      "description": "Desired contract start, ISO YYYY-MM-DD. Omit for the next possible date.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "iban": {
      "type": "string",
      "pattern": "^[A-Z]{2}\\d{2}[A-Z0-9]{10,30}$",
      "description": "IBAN for the SEPA direct-debit mandate, no spaces (e.g. DE89370400440532013000)."
    },
    "accountHolder": {
      "description": "Account holder if different from the contract holder.",
      "type": "string",
      "maxLength": 150
    },
    "consent": {
      "type": "boolean",
      "const": true,
      "description": "The user has explicitly agreed to: (1) Commerce for Agents submitting this contract on their behalf, (2) the provider's contract terms as shown by tariff-details, (3) the SEPA mandate for the given IBAN, (4) the privacy policy — and has been told the contract can be withdrawn within 14 days. True only after that agreement."
    }
  },
  "required": [
    "ref",
    "salutation",
    "firstName",
    "lastName",
    "birthDate",
    "email",
    "street",
    "houseNumber",
    "switchType",
    "iban",
    "consent"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "const": "received"
    },
    "provider": {
      "type": "string"
    },
    "tariff": {
      "type": "string"
    },
    "annualTotalEur": {
      "type": "number"
    },
    "nextSteps": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "status",
    "provider",
    "tariff",
    "annualTotalEur",
    "nextSteps"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Files a concierge switch request for an offer from a comparison: contract data, IBAN and the consents in one call. The booking form opened by start-booking calls it; autonomous MCP clients that hold the user's complete data and authorization can call it directly. Stores the request encrypted, sends the confirmation emails and returns only masked data. An operator later submits the contract application to the provider.

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z0-9]+\\.\\d+$",
      "description": "Offer reference from a compare-tariffs result (field `ref`)."
    },
    "language": {
      "description": "Language of the conversation — used for the confirmation email. Default: \"de\".",
      "type": "string",
      "enum": [
        "de",
        "en"
      ]
    },
    "salutation": {
      "type": "string",
      "enum": [
        "herr",
        "frau",
        "divers"
      ],
      "description": "Salutation (Anrede), required by the providers: \"herr\", \"frau\" or \"divers\"."
    },
    "firstName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "First name (Vorname)."
    },
    "lastName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Last name (Nachname)."
    },
    "birthDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date of birth, ISO format YYYY-MM-DD. Energy providers require it for the contract."
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Email address — receives the booking confirmation and provider documents."
    },
    "phone": {
      "description": "Phone number (optional, some providers ask for it).",
      "type": "string",
      "maxLength": 40
    },
    "street": {
      "type": "string",
      "minLength": 1,
      "maxLength": 150,
      "description": "Street of the supply address (Straße)."
    },
    "houseNumber": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "description": "House number (Hausnummer), e.g. \"12a\"."
    },
    "switchType": {
      "type": "string",
      "enum": [
        "switch",
        "relocation"
      ],
      "description": "\"switch\": changing provider at the current address (Anbieterwechsel). \"relocation\": moving in / first contract at this address (Umzug/Neueinzug)."
    },
    "previousProvider": {
      "description": "Current/previous energy provider. Required for switchType \"switch\".",
      "type": "string",
      "maxLength": 150
    },
    "moveInDate": {
      "description": "Move-in date (Umzugsdatum), ISO YYYY-MM-DD. Required for switchType \"relocation\", ignored for a switch.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "previousCustomerNumber": {
      "description": "Customer number at the previous provider (Kundennummer, optional but speeds up the switch).",
      "type": "string",
      "maxLength": 60
    },
    "meterNumber": {
      "description": "Meter number (Zählernummer, optional — printed on the meter or the last bill).",
      "type": "string",
      "maxLength": 60
    },
    "desiredStartDate": {
      "description": "Desired contract start, ISO YYYY-MM-DD. Omit for the next possible date.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "accountHolder": {
      "description": "Account holder if different from the contract holder.",
      "type": "string",
      "maxLength": 150
    },
    "iban": {
      "type": "string",
      "minLength": 15,
      "maxLength": 40,
      "description": "IBAN as entered in the form; spaces allowed."
    },
    "authorization": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "interactive"
        },
        "contractSubmissionAccepted": {
          "type": "boolean",
          "const": true
        },
        "sepaMandateAccepted": {
          "type": "boolean",
          "const": true
        },
        "privacyPolicyAccepted": {
          "type": "boolean",
          "const": true
        },
        "privacyPolicyVersion": {
          "type": "string"
        },
        "sepaMandateVersion": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "contractSubmissionAccepted",
        "sepaMandateAccepted",
        "privacyPolicyAccepted",
        "privacyPolicyVersion",
        "sepaMandateVersion"
      ],
      "description": "The three consents the user gave in the form, with the wording versions shown to them."
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "description": "Random per form instance. A retry with the same key returns the first result instead of filing twice."
    }
  },
  "required": [
    "ref",
    "salutation",
    "firstName",
    "lastName",
    "birthDate",
    "email",
    "street",
    "houseNumber",
    "switchType",
    "iban",
    "authorization",
    "idempotencyKey"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "const": "received"
    },
    "provider": {
      "type": "string"
    },
    "tariff": {
      "type": "string"
    },
    "annualTotalEur": {
      "type": "number"
    },
    "maskedIban": {
      "type": "string"
    },
    "nextSteps": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "status",
    "provider",
    "tariff",
    "annualTotalEur",
    "maskedIban",
    "nextSteps"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Finds and compares the fixed home internet providers available at a US address or latitude/longitude: fiber, cable, DSL, fixed wireless and satellite, with maximum advertised download and upload speeds and a low-latency flag, ranked by low latency, then speed. Source: FCC Broadband Data Collection at census-block level, so a listed provider may not serve every building in the block; geocoding by the US Census Bureau. Results contain no prices or plans. Optional filters: minDownloadMbps, technology. Keywords: which internet providers are available at my address, internet providers near me, compare internet providers, fastest internet, broadband, ISP, fiber internet, cable internet, home internet comparison.

{
  "type": "object",
  "properties": {
    "address": {
      "description": "US street address incl. city and state or ZIP.",
      "type": "string",
      "minLength": 5
    },
    "lat": {
      "description": "Latitude, if no address is given.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "lon": {
      "description": "Longitude, if no address is given.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "minDownloadMbps": {
      "description": "Only providers advertising at least this download speed.",
      "type": "number",
      "minimum": 0
    },
    "technology": {
      "description": "Only these technologies.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "fiber",
          "cable",
          "dsl",
          "fixed_wireless",
          "satellite",
          "other"
        ]
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}