{
  "openapi": "3.1.0",
  "info": {
    "title": "MovingCost.co.uk removal cost estimate API",
    "version": "1.0.0",
    "summary": "Free UK and UK-to-Europe removal cost estimates as JSON.",
    "description": "Returns the same low/high estimate the MovingCost.co.uk calculator produces, in one GET request. No key required, CORS open, 60 requests per minute per IP. Figures are indicative estimates in GBP excluding VAT (`estimate.includesVat` states which), not quotes. Free to use under CC BY 4.0: display the `source.attribution` line from the response, with its link, wherever you show the figure.",
    "contact": { "name": "MovingCost.co.uk", "email": "hello@movingcost.co.uk", "url": "https://movingcost.co.uk/data" },
    "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }
  },
  "servers": [{ "url": "https://movingcost.co.uk" }],
  "externalDocs": { "description": "Open data and API notes", "url": "https://movingcost.co.uk/data" },
  "paths": {
    "/api/estimate": {
      "get": {
        "operationId": "getRemovalEstimate",
        "summary": "Estimate the cost of a house removal",
        "description": "UK move: pass `size` and either `miles` or a `from`/`to` pair of city slugs. UK to Europe move: pass `country` with `size` or `m3`; the presence of `country` switches to volume-based international pricing and the UK-only parameters are ignored.",
        "parameters": [
          {
            "name": "size",
            "in": "query",
            "description": "Home or storage-unit size. Hyphenated forms such as `3-bed` are accepted. Required for UK moves; for Europe, required unless `m3` is given.",
            "schema": {
              "type": "string",
              "enum": ["1bed", "2bed", "3bed", "4bed", "5bed", "25sqft", "35sqft", "50sqft", "75sqft", "100sqft", "150sqft", "200sqft", "250sqft", "20ftContainer", "40ftContainer"]
            },
            "example": "3bed"
          },
          {
            "name": "miles",
            "in": "query",
            "description": "Road distance in miles, 0 to 1200. UK moves only.",
            "schema": { "type": "number", "minimum": 0, "maximum": 1200 },
            "example": 40
          },
          {
            "name": "from",
            "in": "query",
            "description": "Origin city slug, e.g. `manchester`. Use with `to` instead of `miles`; works for routes the site publishes (city list at https://movingcost.co.uk/removals).",
            "schema": { "type": "string" }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Destination city slug, e.g. `leeds`.",
            "schema": { "type": "string" }
          },
          {
            "name": "collectionType",
            "in": "query",
            "description": "Property type at the origin. Default `house`.",
            "schema": { "type": "string", "enum": ["house", "flat", "bungalow", "storage"] }
          },
          {
            "name": "deliveryType",
            "in": "query",
            "description": "Property type at the destination. Default `house`.",
            "schema": { "type": "string", "enum": ["house", "flat", "bungalow", "storage"] }
          },
          {
            "name": "floors",
            "in": "query",
            "description": "Floor number, 0 to 30, applied to both properties. Default 0.",
            "schema": { "type": "integer", "minimum": 0, "maximum": 30 }
          },
          {
            "name": "lift",
            "in": "query",
            "description": "Whether there is a lift. Default false.",
            "schema": { "type": "boolean" }
          },
          {
            "name": "parking",
            "in": "query",
            "description": "Parking at both properties. Default `onStreet`.",
            "schema": { "type": "string", "enum": ["driveway", "onStreet", "restricted"] }
          },
          {
            "name": "carry",
            "in": "query",
            "description": "Carry distance from van to door. Default `short`.",
            "schema": { "type": "string", "enum": ["short", "medium", "long"] }
          },
          {
            "name": "country",
            "in": "query",
            "description": "Destination country slug for a UK to Europe move, e.g. `spain`. An unknown country returns 400 with the list of valid slugs.",
            "schema": { "type": "string" },
            "example": "spain"
          },
          {
            "name": "m3",
            "in": "query",
            "description": "Volume in cubic metres, for Europe moves, instead of `size`.",
            "schema": { "type": "number" }
          },
          {
            "name": "service",
            "in": "query",
            "description": "Europe moves only. Groupage shares a vehicle; dedicated reserves one. Default `not_sure`.",
            "schema": { "type": "string", "enum": ["groupage", "dedicated", "not_sure"] }
          },
          {
            "name": "packing",
            "in": "query",
            "description": "Europe moves only. Include a packing service.",
            "schema": { "type": "boolean" }
          },
          {
            "name": "storage",
            "in": "query",
            "description": "Europe moves only. Include storage.",
            "schema": { "type": "boolean" }
          }
        ],
        "responses": {
          "200": {
            "description": "An estimate.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Estimate" },
                "example": {
                  "ok": true,
                  "estimate": { "low": 692, "high": 936, "currency": "GBP", "includesVat": false },
                  "source": {
                    "name": "MovingCost.co.uk",
                    "url": "https://movingcost.co.uk/calculator",
                    "license": "https://creativecommons.org/licenses/by/4.0/",
                    "attribution": "Estimate from the MovingCost.co.uk moving cost calculator - https://movingcost.co.uk/calculator"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid parameters. The body says what is wrong and lists valid values.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Rate limit exceeded (60 requests per minute per IP).",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Estimate": {
        "type": "object",
        "required": ["ok", "estimate", "source"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "estimate": {
            "type": "object",
            "description": "The price range. Quote both ends; the true price depends on inventory, access and date.",
            "properties": {
              "low": { "type": "number" },
              "high": { "type": "number" },
              "currency": { "type": "string", "const": "GBP" },
              "includesVat": { "type": "boolean" }
            }
          },
          "source": {
            "type": "object",
            "description": "Credit line to display alongside the figure.",
            "properties": {
              "name": { "type": "string" },
              "url": { "type": "string", "format": "uri" },
              "license": { "type": "string", "format": "uri" },
              "attribution": { "type": "string" }
            }
          },
          "breakdown": { "type": "object", "description": "UK moves: cost components behind the estimate." },
          "job": { "type": ["object", "null"], "description": "UK moves: crew, vehicle and time assumed." },
          "journey": { "type": "object", "description": "Europe moves: van loads and crossing cost." },
          "input": { "type": "object", "description": "The inputs as resolved, including defaults applied." },
          "assumptions": { "type": "array", "items": { "type": "string" } },
          "notes": { "type": "string" },
          "links": { "type": "object", "description": "Related pages on movingcost.co.uk." }
        }
      },
      "Error": {
        "type": "object",
        "required": ["ok", "error"],
        "properties": {
          "ok": { "type": "boolean", "const": false },
          "error": { "type": "string" }
        }
      }
    }
  }
}
