The Finto AI API service offers the same functionality as the Finto AI form user interface - in fact, the form is based on the same API. The API is given text and it responds with subject suggestions. Each suggestion contains a concept URI, a term (label) and a score in the range 0.0-1.0, which reflects the estimated relevance of the subject for the input document.

Take note of the following if you want to use the API:

  1. The API accepts raw text. If your documents are in another format, such as PDF, HTML or Word, you must first convert it to UTF-8 encoded raw text.
  2. The API offers so-called projects and the API request must be targeted at the correct project according to the language of the document. If the document language is unknown, you must first determine it using another tool (see e.g. the SeCo LAS API and the langdetect library for Python). There are currently three projects: yso-fi, yso-sv and yso-en.
  3. The API has several methods. The most important are the list of projects (/v1/projects/) and suggesting subjects for documents (/v1/projects/<project_id>/suggest). You can control the number of suggestions using the limit and threshold parameters. The limit parameter sets the maximum number of suggestions (default 10) and the threshold sets the minimum score level for suggestions.
  4. There are currently no limitations on the use of the API. To avoid overloading the API, please do not make multiple parallel calls - wait for the previous request to finish before making a new one. The maximum input size is 5 MB.

A detailed, interactive OpenAPI/Swagger documentation for the API is available.

API service users

The Finto AI/Annif API service is being used in the JYX repository of the University of Jyväskylä, where it is used to assist the subject indexing of Master's theses. Students uploading their thesis get automatic suggestions for subjects, which they can then select and modify. The final subjects are confirmed by a librarian. A similar workflow is also in use at several institutional repositories maintained by the National Library of Finland. Also, Kirjavälitys Oy is using the API service for generating metadata about upcoming book titles.

Automated subject suggestions in the JYX repository