Quickstart#

This tutorial will help you get started with the Tonita API through our Python library. We will walk through an example of how listings and corpora can be used to prepare and organize data. We will then go over some of the ways in which search can be performed, as well as how search results can be evaluated.

Before proceeding with the tutorial, make sure that you have an API key (see Authentication) and that the Tonita Python library is installed (see Installation). It would also be helpful to review Key concepts.

Note

In addition to the Tonita Python library, we also provide HTTP endpoints. While this tutorial will focus primarily on our Python library, we also offer examples that make requests to these HTTP endpoints directly using curl. See Making HTTP requests for more information.

Setting a default API key#

We first import the client library and set a default API key for API calls.

import tonita

tonita.api_key = "my_api_key"

This signals that subsequent calls that do not provide an API key will default to this value instead. See API keys and corpus IDs for other ways the API key can be set in the Python library.

Creating a corpus#

We must first create a corpus to populate with listings. To add a corpus, simply make the following call:

Python

tonita.corpora.add(corpus_id="nyc_housing")

# Example return value:
# AddCorpusResponse(corpus_id='nyc_housing')

cURL

curl -X POST -H "content-type: application/json" \
    -H "x-api-key: my_api_key" \
    -d '{"corpus_id": "nyc_housing"}' \
    https://api.tonita.co/corpora/add

# Example response value:
# {"corpus_id": "nyc_housing"}

AddCorpusResponse is a Python dataclass that contains the response data for your request to add a corpus. Each call to a Tonita API endpoint using the Python library will return a dataclass containing the response data. See Request and response types types for more information.

We can then confirm its existence by listing all corpora associated with this API key:

Python

tonita.corpora.list()

# Example return value:
# ListCorporaResponse(results={"nyc_housing": <State.ACTIVE: 'ACTIVE'>})

cURL

curl -X POST -H "content-type: application/json" \
    -H "x-api-key: my_api_key" \
    https://api.tonita.co/corpora/list

# Example response value:
# {"results": {"nyc_housing": "ACTIVE"}}

Or check that, in particular, the corpus we just created exists:

Python

tonita.corpora.get(corpus_id="nyc_housing")

# Example return value:
# GetCorpusResponse(
#     corpus_id='nyc_housing', 
#     exists=True, 
#     state=<State.ACTIVE: 'ACTIVE'>, 
#     seconds_to_expiration=None
# )

cURL

curl -X POST -H "content-type: application/json" \
    -H "x-api-key: my_api_key" \
    -d '{"corpus_id": "nyc_housing"}' \
    https://api.tonita.co/corpora/get

# Example response value:
# {
#   "corpus_id": "nyc_housing", 
#   "exists": true, 
#   "state": "ACTIVE", 
#   "seconds_to_expiration": null
# }

To create another corpus, simply make another call to tonita.corpora.add. Note that corpus IDs must be unique for a given API key.

Python

tonita.corpora.add(corpus_id="movies")

# Example return value:
# AddCorpusResponse(corpus_id='movies')

tonita.corpora.list()

# Example return value:
# ListCorporaResponse(
#     results={
#         "movies": <State.ACTIVE: 'ACTIVE'>,
#         "nyc_housing": <State.ACTIVE: 'ACTIVE'>
#     }
# )

cURL

curl -X POST -H "content-type: application/json" \
    -H "x-api-key: my_api_key" \
    -d '{"corpus_id": "movies"}' \
    https://api.tonita.co/corpora/add

# Example response value:
# {"corpus_id": "movies"}

curl -X POST -H "content-type: application/json" \
    -H "x-api-key: my_api_key" \
    https://api.tonita.co/corpora/list

# Example response value:
# {
#   "results": {
#     "movies": "ACTIVE", 
#     "nyc_housing": "ACTIVE"
#   }
# }

Performing search#

Tonita will work with you to learn how to best process the data that you’ve provided, and build a search engine for you. This will take some time; we will notify you when a search engine is ready. (If you wish to obtain the models and integrate with your existing search engine, reach out to us at hello@tonita.co, and we’d be happy to work with you.)

Once we’ve provided you with a search engine, you can perform search.

For example, suppose we want to perform search over the listings in our "nyc_housing" corpus. We’d simply call tonita.search():

Python

tonita.search(
    query='sunny 1 bedroom on a quiet street near parks',
    max_results=2,
    categories=["co-op", "condo"]
)

cURL

curl -X POST -H "content-type: application/json" \
    -H "x-api-key: my_api_key" \
    -H "corpus-id: nyc_housing" \
    -d '{"query": "sunny 1 bedroom on a quiet street near parks", "max_results": 2, "categories": ["co-op", "condo"]}' \
    https://api.tonita.co/search

In this example, we simply want the ten listings most relevant to our given query string, but the Tonita search API provides a host of ways in which search can be performed: you can also search for similar listings by providing a listing ID, and there are options for restricting search by category and facet values. See our guide on performing search for details.

The response will be returned in a SearchResponse dataclass. Let’s look at one sample response.

Python

SearchResponse(
    items=[
        SearchResponseItem(
            listing_id="h298921md",
            score=1.172,
            categories=["apartment", "condo"],
            snippets=[
                Snippet(
                    display_string="South and east exposures."
                ),
                Snippet(
                    display_string="Steps from McCarren Park."
                )
            ],
        ),
        SearchResponseItem(
            listing_id="h197233sm",
            score=0.239,
            categories=["apartment", "co-op"],
            snippets=[
                Snippet(
                    display_string="Oversized one-bedroom."
                )
            ]
        )
    ]
)

cURL

{
  "items": [
    {
      "listing_id": "h298921md",
      "score": 1.172,
      "categories": [
        "apartment",
        "condo"
      ],
      "snippets": [
        {
          "display_string": "South and east exposures."
        },
        {
          "display_string": "Steps from McCarren Park."
        }
      ]
    },
    {
      "listing_id": "h197233sm",
      "score": 0.239,
      "categories": [
        "apartment",
        "co-op"
      ],
      "snippets": [
        {
          "display_string": "Oversized one-bedroom."
        }
      ]
    }
  ]
}

Here, two relevant listings were returned. Note that the response sorts listing results in descending order of relevance score, and returns each listing ID with its score, the matching categories, and some strings (“snippets”) that explain why that result was returned. For more details about this response object, see our guide on performing search.

And voilà! We’ve completed our first search.

Quickstart#

Setting a default API key#

Creating a corpus#

Adding listings#

Performing search#