Query Parameters¶

When you declare other function parameters that are not part of the path parameters, they are automatically interpreted as "query" parameters.

fromfastapiimportFastAPIapp=FastAPI()fake_items_db=[{"item_name":"Foo"},{"item_name":"Bar"},{"item_name":"Baz"}]@app.get("/items/")asyncdefread_item(skip:int=0,limit:int=10):returnfake_items_db[skip:skip+limit]

The query is the set of key-value pairs that go after the? in a URL, separated by& characters.

For example, in the URL:

http://127.0.0.1:8000/items/?skip=0&limit=10

...the query parameters are:

• skip: with a value of0
• limit: with a value of10

As they are part of the URL, they are "naturally" strings.

But when you declare them with Python types (in the example above, asint), they are converted to that type and validated against it.

All the same process that applied for path parameters also applies for query parameters:

• Editor support (obviously)
• Data"parsing"
• Data validation
• Automatic documentation

Defaults¶

As query parameters are not a fixed part of a path, they can be optional and can have default values.

In the example above they have default values ofskip=0 andlimit=10.

So, going to the URL:

http://127.0.0.1:8000/items/

would be the same as going to:

http://127.0.0.1:8000/items/?skip=0&limit=10

But if you go to, for example:

http://127.0.0.1:8000/items/?skip=20

The parameter values in your function will be:

• skip=20: because you set it in the URL
• limit=10: because that was the default value

Optional parameters¶

The same way, you can declare optional query parameters, by setting their default toNone:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_item(item_id:str,q:str|None=None):ifq:return{"item_id":item_id,"q":q}return{"item_id":item_id}

In this case, the function parameterq will be optional, and will beNone by default.

Query parameter type conversion¶

You can also declarebool types, and they will be converted:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_item(item_id:str,q:str|None=None,short:bool=False):item={"item_id":item_id}ifq:item.update({"q":q})ifnotshort:item.update({"description":"This is an amazing item that has a long description"})returnitem

In this case, if you go to:

http://127.0.0.1:8000/items/foo?short=1

or

http://127.0.0.1:8000/items/foo?short=True

or

http://127.0.0.1:8000/items/foo?short=true

or

http://127.0.0.1:8000/items/foo?short=on

or

http://127.0.0.1:8000/items/foo?short=yes

or any other case variation (uppercase, first letter in uppercase, etc), your function will see the parametershort with abool value ofTrue. Otherwise asFalse.

Multiple path and query parameters¶

You can declare multiple path parameters and query parameters at the same time,FastAPI knows which is which.

And you don't have to declare them in any specific order.

They will be detected by name:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/users/{user_id}/items/{item_id}")asyncdefread_user_item(user_id:int,item_id:str,q:str|None=None,short:bool=False):item={"item_id":item_id,"owner_id":user_id}ifq:item.update({"q":q})ifnotshort:item.update({"description":"This is an amazing item that has a long description"})returnitem

Required query parameters¶

When you declare a default value for non-path parameters (for now, we have only seen query parameters), then it is not required.

If you don't want to add a specific value but just make it optional, set the default asNone.

But when you want to make a query parameter required, you can just not declare any default value:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_user_item(item_id:str,needy:str):item={"item_id":item_id,"needy":needy}returnitem

Here the query parameterneedy is a required query parameter of typestr.

If you open in your browser a URL like:

http://127.0.0.1:8000/items/foo-item

...without adding the required parameterneedy, you will see an error like:

{"detail":[{"type":"missing","loc":["query","needy"],"msg":"Field required","input":null}]}

Asneedy is a required parameter, you would need to set it in the URL:

http://127.0.0.1:8000/items/foo-item?needy=sooooneedy

...this would work:

{"item_id":"foo-item","needy":"sooooneedy"}

And of course, you can define some parameters as required, some as having a default value, and some entirely optional:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_user_item(item_id:str,needy:str,skip:int=0,limit:int|None=None):item={"item_id":item_id,"needy":needy,"skip":skip,"limit":limit}returnitem

In this case, there are 3 query parameters:

• needy, a requiredstr.
• skip, anint with a default value of0.
• limit, an optionalint.