API keys and corpus IDs#

Providing an API key#

Functions in this library make requests to Tonita’s API server. In order for requests to be processed, an API key must be specified with each API call. (See Authentication to learn how to request an API key). There are three ways to specify the API key when using the Tonita Python library.

Set the TONITA_API_KEY environment variable (recommended, so you don’t have keys exposed within your code):
```
export TONITA_API_KEY = "my_api_key"
```
Upon importing the Tonita library in Python, tonita.api_key will be set to this value.
Set the value of the tonita.api_key variable in Python after import:
```
import tonita
tonita.api_key = "my_api_key"
```
If the value of tonita.api_key is set using this method, it will overwrite the value of tonita.api_key provided by the environment variable TONITA_API_KEY.

Pass an api_key with each request. For example:

import tonita

# Add a listing to a corpus.
tonita.listings.add(
    json_path="path/to/data.json"
    corpus_id="my_corpus_id",
    api_key="my_api_key"
)

If an API key is provided this way, it will take precedence over both the value of TONITA_API_KEY and tonita.api_key.

If an API key is not provided, a TonitaAPIRequestError will be raised.

Providing a corpus ID#

In addition to the API key, a corpus ID must also be provided for many requests (for example, when creating or deleting corpora, when working with listings, and when performing search).

There are two ways to set the corpus ID:

Set the value of the tonita.corpus_id variable in Python after import:
```
import tonita
tonita.corpus_id = "my_corpus_id"
```

Pass a corpus_id with the request. For example:

import tonita

tonita.api_key = "my_api_key"

tonita.search(
    query='sunny 1 bedroom on a quiet street near parks',
    max_results=20,
    categories=["manhattan", "brooklyn"],
    corpus_id="my_corpus_id"
)

If a corpus ID is provided this way, it will take precedence over the value of tonita.corpus_id.

If a corpus ID is not provided anywhere when calling a function that requires it, a TonitaAPIRequestError will be raised.