Query Parameters in FastAPI

What are Query Parameters?

In FastAPI, query parameters are used to pass optional data in the URL after the ? symbol, and they are typically used to filter, search, or customize the response from the server.

from fastapi import FastAPI

app = FastAPI()

@app.get("/greet/")
def greet_user(name: str):
    return {"message": f"Hello, {name}!"}

# http://localhost:8000/greet/?name=Abhishek

Query Parameter with Type Conversion

FastAPI automatically converts query parameters to the specified data types. It also validates them and returns an error if the type doesn't match.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def get_items(in_stock: bool = False):
    return {"in_stock": in_stock}

# http://localhost:8000/items/?in_stock=true

Multiple Query Parameters

Multiple query parameters allow you to pass more than one key-value pair in the URL, separated by &. In FastAPI, they are automatically parsed and passed as function arguments.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def get_items(category: str, limit: int = 10):
    return {"filtered_by": category, "limit": limit}

# http://localhost:8000/items/?category=books&limit=20

List of Query Parameters

A list of query parameters lets clients send multiple values with the same key. In FastAPI, you declare the parameter as a List type, and it automatically gathers all values into a Python list, making it easy to handle multiple inputs in one request.

from fastapi import FastAPI

app = FastAPI()

@app.get("/search/")
def search_tags(tags: list[str]):
    return {"tags": tags}

# http://localhost:8000/search/?tags=python&tags=fastapi

Required and Optional Parameters

In FastAPI, required query parameters must be included in the request URL and have no default value. Optional query parameters have a default value, allowing them to be omitted by the client.

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/")
def get_users(name: str, age: int | None = None):
    return {"name": name, "age": age}

# http://localhost:8000/users/?name=Abhishek&age=26
# http://localhost:8000/users/?name=Abhishek

Using Path and Query Parameters

Path parameters are part of the URL path and are used to identify specific resources, while query parameters are appended to the URL to filter or customize the response. FastAPI supports both, letting you easily capture values from the path and the query string.

from fastapi import FastAPI

app = FastAPI()

@app.get("/products/{product_id}")
def get_product(product_id: int, detail: bool = False):
    return {"product_id": product_id, "detail": detail}

# http://localhost:8000/products/123?detail=true

Exercise