YouTip

Query parameters are the key-value pairs after `?` in the URL, separated by `&`. When a function parameter is neither a path parameter nor a request body, FastAPI automatically interprets it as a query parameter.\n\n* * *\n\n## Basic Usage\n\nDeclaring query parameters only requires adding type annotations and default values to the function parameters:\n\n## Example\n\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n# skip and limit are query parameters with default values\n\n fake_items_db =[{"item_name": "Foo"},{"item_name": "Bar"},{"item_name": "Baz"}]\n\n@app.get("/items/")\n\n async def read_item(skip: int=0, limit: int=10):\n\n# Simulating pagination query\n\nreturn fake_items_db[skip : skip + limit]\n\nQuery parameters in URL format:\n\nhttp://127.0.0.1:8000/items/?skip=0&limit=10\nParameter values for different access methods:\n\n| URL | skip Value | limit Value | Description |\n| --- | --- | --- | --- |\n| `/items/` | `0` | `10` | Uses default values |\n| `/items/?skip=20` | `20` | `10` | skip uses passed value, limit uses default value |\n| `/items/?skip=20&limit=5` | `20` | `5` | Both parameters use passed values |\n\n* * *\n\n## Optional Parameters\n\nSet the default value to `None` to declare optional query parameters:\n\n## Example\n\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get("/items/{item_id}")\n\n async def read_item(item_id: str, q: str | None=None):\n\n# item_id is a path parameter (required), q is a query parameter (optional)\n\nif q:\n\nreturn{"item_id": item_id,"q": q}\n\nreturn{"item_id": item_id}\n\nHere `q: str | None = None` means `q` can be a string or `None`, with a default value of `None`.\n\n> FastAPI determines whether a parameter is required through the default value `= None`, not through the type annotation `str | None`. Type annotations mainly help editors provide better support.\n\n* * *\n\n## Query Parameter Type Conversion\n\nFastAPI supports automatic conversion of query parameters to `bool` type:\n\n## Example\n\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get("/items/{item_id}")\n\n async def read_item(item_id: str, short: bool=False):\n\n# short parameter will be automatically converted to boolean\n\nif short:\n\nreturn{"item_id": item_id}\n\nreturn{"item_id": item_id,"description": "This is a very long description"}\n\nThe following URLs with `short` parameter will all be converted to `True`:\n\n/items/foo?short=1/items/foo?short=True/items/foo?short=true/items/foo?short=on /items/foo?short=yes\nOther values will be converted to `False`.\n\n* * *\n\n## Required Query Parameters\n\nQuery parameters without default values are required parameters:\n\n## Example\n\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get("/items/{item_id}")\n\n async def read_item(item_id: str, needy: str):\n\n# needy has no default value, it is a required query parameter\n\nreturn{"item_id": item_id,"needy": needy}\n\nIf you access `/items/foo` without providing the `needy` parameter, FastAPI will return an error similar to:\n\n{ "detail": [ { "type": "missing", "loc": ["query", "needy"], "msg": "Field required", "input": null } ]}\n\n* * *\n\n## Mixing Required, Default, and Optional Parameters\n\nYou can mix different types of query parameters in the same function:\n\n## Example\n\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get("/items/{item_id}")\n\n async def read_item(\n\n item_id: str,# Path parameter (required)\n\n needy: str,# Required query parameter\n\n skip: int=0,# Query parameter with default value\n\n limit: int | None=None,# Optional query parameter\n\n):\n\n item ={"item_id": item_id,"needy": needy,"skip": skip}\n\nif limit:\n\n item.update({"limit": limit})\n\nreturn item\n\nParameter type summary:\n\n| Parameter | Declaration | Required | Description |\n| --- | --- | --- | --- |\n| `item_id` | `item_id: str` | Required | Path parameter, appears in URL path |\n| `needy` | `needy: str` | Required | Query parameter, no default value |\n| `skip` | `skip: int = 0` | Optional | Query parameter, default value 0 |\n| `limit` | `limit: int | None = None` | Optional | Query parameter, default value None |\n\n* * *\n\n## Multiple Path and Query Parameters\n\nFastAPI can recognize multiple path parameters and query parameters simultaneously; the order of parameter declaration does not affect recognition:\n\n## Example\n\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get("/users/{user_id}/items/{item_id}")\n\n async def read_user_item(\n\n user_id: int,# Path parameter\n\n item_id: str,# Path parameter\n\n q: str | None=None,# Optional query parameter\n\n short: bool=False,# Query parameter with default value\n\n):\n\n item ={"item_id": item_id,"owner_id": user_id}\n\nif q:\n\n item.update({"q": q})\n\nif not short:\n\n item.update({"description": "This is a very long description"})\n\nreturn item\n\nFastAPI matches variables in the path through parameter names, so the order of function parameters does not matter.\n\n* * *\n\n## Summary\n\nCore points of query parameters:\n\n* Parameters with default values are optional, those without default values are required\n* FastAPI automatically converts strings in the URL to the declared type\n* `bool` type supports multiple formats (`true`, `1`, `on`, `yes`, etc.)\n* Query parameters can be mixed with path parameters, order is irrelevant