{
  "openapi": "3.1.0",
  "info": {
    "title": "UnitGlide Conversion API",
    "version": "1.0.0",
    "summary": "Free, key-less unit conversion and reference factors.",
    "description": "A read-only JSON API over the same conversion factors the UnitGlide site itself uses. No key, no sign-up, CORS-open, GET only. There is no server-side state, so there is no per-key quota and no enforced rate limit; the documented fair-use expectation is on https://unitglide.net/developers. Endpoint changes are logged at https://unitglide.net/developers/changelog.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "UnitGlide",
      "url": "https://unitglide.net/contact"
    }
  },
  "servers": [
    {
      "url": "https://unitglide.net",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "convert",
      "description": "Value conversion."
    },
    {
      "name": "reference",
      "description": "Unit catalogue and conversion factors."
    }
  ],
  "paths": {
    "/api/v1/convert": {
      "get": {
        "tags": [
          "convert"
        ],
        "operationId": "convert",
        "summary": "Convert a value between two units of the same category.",
        "description": "Both units must belong to the same category, otherwise the endpoint returns 400 with an explanation. `result` is the full-precision number, `formatted` the trimmed display value.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "Source unit id, for example `kg`. Case-insensitive. Ids are listed by /api/v1/units.",
            "schema": {
              "type": "string",
              "examples": [
                "kg"
              ]
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "Target unit id, for example `lb`. Case-insensitive. Must be in the same category as `from`.",
            "schema": {
              "type": "string",
              "examples": [
                "lb"
              ]
            }
          },
          {
            "name": "value",
            "in": "query",
            "required": false,
            "description": "Numeric value to convert. Defaults to 1. Must be a finite number.",
            "schema": {
              "type": "number",
              "default": 1,
              "examples": [
                5
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Conversion result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "category",
                    "value",
                    "from",
                    "to",
                    "result",
                    "formatted",
                    "source",
                    "license",
                    "attribution"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "category": {
                      "type": "string",
                      "description": "Category id shared by both units."
                    },
                    "value": {
                      "type": "number",
                      "description": "The input value that was converted."
                    },
                    "from": {
                      "type": "object",
                      "required": [
                        "id",
                        "name",
                        "symbol"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Stable unit id used in URLs and in the from/to parameters."
                        },
                        "name": {
                          "type": "string"
                        },
                        "symbol": {
                          "type": "string"
                        }
                      }
                    },
                    "to": {
                      "type": "object",
                      "required": [
                        "id",
                        "name",
                        "symbol"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Stable unit id used in URLs and in the from/to parameters."
                        },
                        "name": {
                          "type": "string"
                        },
                        "symbol": {
                          "type": "string"
                        }
                      }
                    },
                    "result": {
                      "type": "number",
                      "description": "Full-precision converted value."
                    },
                    "formatted": {
                      "type": "string",
                      "description": "Display-trimmed value."
                    },
                    "source": {
                      "type": "string",
                      "format": "uri",
                      "description": "Human-readable page for this conversion."
                    },
                    "license": {
                      "type": "string",
                      "format": "uri",
                      "description": "Licence the returned data is published under."
                    },
                    "attribution": {
                      "type": "string",
                      "description": "Attribution line to use when republishing the data."
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "category": "mass",
                  "value": 5,
                  "from": {
                    "id": "kg",
                    "name": "Kilogram",
                    "symbol": "kg"
                  },
                  "to": {
                    "id": "lb",
                    "name": "Pound",
                    "symbol": "lb"
                  },
                  "result": 11.023113109243878,
                  "formatted": "11.0231",
                  "source": "https://unitglide.net/convert/kg-to-lb",
                  "license": "https://creativecommons.org/licenses/by/4.0/",
                  "attribution": "UnitGlide, https://unitglide.net"
                }
              }
            }
          },
          "400": {
            "description": "Missing parameter, unknown unit id, mismatched categories, or a non-numeric value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "ok": false,
                  "error": "Unknown unit 'banana'.",
                  "license": "https://creativecommons.org/licenses/by/4.0/",
                  "attribution": "UnitGlide, https://unitglide.net"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/units": {
      "get": {
        "tags": [
          "reference"
        ],
        "operationId": "listUnits",
        "summary": "List every category and the unit ids it contains.",
        "description": "Use this to discover valid `from` and `to` values for /api/v1/convert.",
        "responses": {
          "200": {
            "description": "The full unit catalogue.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "categories",
                    "license",
                    "attribution"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "name",
                          "baseUnit",
                          "units"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "baseUnit": {
                            "type": "string",
                            "description": "Unit id of this category's base unit."
                          },
                          "units": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "id",
                                "name",
                                "symbol"
                              ],
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "Stable unit id used in URLs and in the from/to parameters."
                                },
                                "name": {
                                  "type": "string"
                                },
                                "symbol": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "license": {
                      "type": "string",
                      "format": "uri",
                      "description": "Licence the returned data is published under."
                    },
                    "attribution": {
                      "type": "string",
                      "description": "Attribution line to use when republishing the data."
                    }
                  }
                },
                "examples": {
                  "abridged": {
                    "summary": "Abridged: the live response lists every category.",
                    "value": {
                      "ok": true,
                      "categories": [
                        {
                          "id": "mass",
                          "name": "Mass",
                          "baseUnit": "kg",
                          "units": [
                            {
                              "id": "kg",
                              "name": "Kilogram",
                              "symbol": "kg"
                            },
                            {
                              "id": "lb",
                              "name": "Pound",
                              "symbol": "lb"
                            }
                          ]
                        }
                      ],
                      "license": "https://creativecommons.org/licenses/by/4.0/",
                      "attribution": "UnitGlide, https://unitglide.net"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/factors": {
      "get": {
        "tags": [
          "reference"
        ],
        "operationId": "listFactors",
        "summary": "Conversion factor to the base unit for every unit, with exactness and source.",
        "description": "The machine-readable version of https://unitglide.net/methodology. `factorToBase` is the number of base units in one of this unit, and is null for temperature, which converts by formula rather than by a factor. `exact` is true when the value shown is the exact defined value, false when the definition is exact but not a terminating decimal or the value is rounded, and null when exactness cannot be asserted honestly.",
        "responses": {
          "200": {
            "description": "Factor table.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "categories",
                    "units",
                    "license",
                    "attribution"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "about": {
                      "type": "string"
                    },
                    "exactness": {
                      "type": "object",
                      "description": "Plain-language meaning of each value of the `exact` flag.",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "name",
                          "baseUnit",
                          "sources"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "baseUnit": {
                            "type": "string"
                          },
                          "sources": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "label",
                                "url"
                              ],
                              "properties": {
                                "label": {
                                  "type": "string"
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "units": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "name",
                          "symbol",
                          "category",
                          "baseUnit",
                          "factorToBase",
                          "exact",
                          "source"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "symbol": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "categoryName": {
                            "type": "string"
                          },
                          "baseUnit": {
                            "type": "object",
                            "required": [
                              "id",
                              "name",
                              "symbol"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "Stable unit id used in URLs and in the from/to parameters."
                              },
                              "name": {
                                "type": "string"
                              },
                              "symbol": {
                                "type": "string"
                              }
                            }
                          },
                          "factorToBase": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Base units per one of this unit. Null for temperature."
                          },
                          "exact": {
                            "type": [
                              "boolean",
                              "null"
                            ],
                            "description": "True if the factor shown is the exact defined value, false if rounded or non-terminating, null if not asserted."
                          },
                          "source": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Authority defining the factor, if one does."
                          },
                          "sourceUrl": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "uri"
                          },
                          "note": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "How the factor is derived, or why exactness is not asserted."
                          }
                        }
                      }
                    },
                    "license": {
                      "type": "string",
                      "format": "uri",
                      "description": "Licence the returned data is published under."
                    },
                    "attribution": {
                      "type": "string",
                      "description": "Attribution line to use when republishing the data."
                    }
                  }
                },
                "examples": {
                  "abridged": {
                    "summary": "Abridged: the live response lists every unit in every category.",
                    "value": {
                      "ok": true,
                      "units": [
                        {
                          "id": "lb",
                          "name": "Pound",
                          "symbol": "lb",
                          "category": "mass",
                          "categoryName": "Mass",
                          "baseUnit": {
                            "id": "kg",
                            "name": "Kilogram",
                            "symbol": "kg"
                          },
                          "factorToBase": 0.45359237,
                          "exact": true,
                          "source": "NIST Handbook 44, Appendix C: General Tables of Units of Measurement",
                          "sourceUrl": "https://www.nist.gov/document/2026-nist-handbook-44-appendix-c",
                          "note": "The avoirdupois pound is exactly 0.45359237 kg. Fixed by the 1959 international yard and pound agreement, and therefore exact."
                        },
                        {
                          "id": "kph",
                          "name": "Kilometer per hour",
                          "symbol": "km/h",
                          "category": "speed",
                          "categoryName": "Speed",
                          "baseUnit": {
                            "id": "mps",
                            "name": "Meter per second",
                            "symbol": "m/s"
                          },
                          "factorToBase": 0.2777777777777778,
                          "exact": false,
                          "source": "NIST Special Publication 811, Guide for the Use of the International System of Units",
                          "sourceUrl": "https://www.nist.gov/pml/special-publication-811",
                          "note": "Defined exactly as 1/3.6 m/s, which is a repeating decimal. The figure here is that exact ratio rounded to double precision."
                        }
                      ],
                      "license": "https://creativecommons.org/licenses/by/4.0/",
                      "attribution": "UnitGlide, https://unitglide.net"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "error",
          "license",
          "attribution"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string",
            "description": "Human-readable explanation of what was wrong with the request."
          },
          "license": {
            "type": "string",
            "format": "uri",
            "description": "Licence the returned data is published under."
          },
          "attribution": {
            "type": "string",
            "description": "Attribution line to use when republishing the data."
          }
        }
      }
    }
  }
}