Finnish Companion API Documentation
This guide will help you understand and get started with the Finnish Companion API.
Base URL
https://api2.finnishcompanion.com
All requests should be made to this base URL.
API Endpoints
Quick Navigation
Error Codes
The API uses consistent error codes in its JSON error responses. Common error codes include:
ERR_NO_TERM: No term was provided.ERR_INVALID_QUERY: Invalid query parameters.ERR_PROCESSING: Error processing the request.ERR_SERVER: Internal server error.ERR_NO_RESULTS: No results found.
Root
Path
/
Description
A welcome message.
Input Parameters
None
Output
Plain text: "Welcome to the Finnish Companion API!"
Example
/
Kotus
Path
/kotus
Description
Retrieves Kotus information (the conjugation group from the Kielitoimisto) for a Finnish word.
Input Parameters
term(string, required): The Finnish word to look up.
Output
A JSON object containing Kotus data. The structure of this object depends on the word and Kotus categories. Returns an empty object {} if no results are found.
Example
/kotus?term=talossa
Part of Speech
Path
/pos
Description
Determines the Part of Speech (POS) of a Finnish word.
Input Parameters
term(string, required): The Finnish word to analyze.
Output
A JSON array of objects, where each object contains the pos (part of speech) tag for the term. Returns an empty array [] if no results are found.
Example
/pos?term=kirja
Vartalo (Stem)
Path
/vartalo
Description
Retrieves the stem ("vartalo") of a Finnish word.
Input Parameters
term(string, required): The Finnish word.
Output
A JSON object containing the stem. Returns an empty object {} if no results are found. The structure of the object will depend on the word.
Example
/vartalo?term=kirjat
Conjugate
Path
/conjugate
Description
Conjugates Finnish verbs and nouns.
Options
Specify either command, or verb OR noun
If verb
- pronoun (string, optional): The pronoun to conjugate for (e.g., "minä", "sinä").
- tense (string, optional): The tense to conjugate for (e.g. present, past).
- mood (string, optional): The mood to conjugate for (e.g. indicative, conditional).
If noun
- case (string, optional): The case to conjugate for (e.g., "genitive", "essive").
If command
- String of a word or phrase to conjugate.
Input Parameters
verb(string, optional): The verb to conjugate.
noun(string, optional): The noun to conjugate.
command(string, optional): A command.
Output
A JSON object containing the conjugated forms. The structure depends on whether a verb or noun was conjugated.
Example
/conjugate?verb=olla&pronoun=minä&tense=present
/conjugate?noun=kirja&case=genitive
/conjugate?command=mene
Quick Conjugate
Path
/quickconjugate
Description
Quickly determines the term type (verb or noun) and conjugates it.
Input Parameters
term(string, required): The term to conjugate.
verb(string, optional): A verb to assist in conjugation. Defaults to an empty string.
noun(string, optional): A noun to assist in conjugation. Defaults to an empty string.
Output
A JSON object containing the conjugated forms.
Example
/quickconjugate?term=mennä
Reverse Conjugate
Path
/reverseconjugate
Description
Attempts to reverse-conjugate a Finnish word to find its base form.
Input Parameters
term(string, required): The conjugated Finnish word.
Output
A JSON object containing possible base forms. The structure of the object depends on the results. Returns an empty object {} if no results are found.
Example
/reverseconjugate?term=menemme
Breakdown Phrase
Path
/breakdownphrase
Description
Breaks down a Finnish phrase into its constituent parts.
Input Parameters
term(string, required): The phrase to break down.
Output
A JSON object representing the breakdown of the phrase. Returns an empty object {} if no results are found. The structure depends on the phrase.
Example
/breakdownphrase?term=iso punainen auto
Breakdown
Path
/breakdown
Description
Breaks down a compound Finnish word into its component words.
Input Parameters
term(string, required): The compound word.
Output
A JSON object representing the breakdown of the word. Returns an empty object {} if no results are found. The structure depends on the word.
Example
/breakdown?term=jääkaappi
Syllable
Path
/syllable
Description
Hyphenates a Finnish word into syllables.
Input Parameters
term(string, required): The word to hyphenate.
Output
A JSON object containing the hyphenated word. Returns an empty object {} if no results are found. The structure depends on the word.
Example
/syllable?term=kirjoittaa
Readable
Path
/readable
Description
Makes a Finnish word more readable or pronounceable.
Input Parameters
term(string, required): The word to make readable.
Output
A JSON object containing the readable version of the word. Returns an empty object {} if no results are found. The structure depends on the word.
Example
/readable?term=epäjärjestelmällisyys
To Finnish
Path
/tofinnish
Description
Translates a word/phrase from any supported language to Finnish.
Input Parameters
term(string, required): The word/phrase to translate.
from(string, optional): Language code of origin language.
Output
A JSON object containing the translation. Returns an empty object {} if no results are found. The structure depends on the translation.
Example
/tofinnish?term=hello&from=en
From Finnish
Path
/fromfinnish
Description
Translates a word/phrase from Finnish to any supported language.
Input Parameters
term(string, required): The word/phrase to translate.
to(string, optional): Language code of target language.
Output
A JSON object containing the translation. Returns an empty object {} if no results are found. The structure depends on the translation.
Example
/fromfinnish?term=hei&to=en
Speak
Path
/speak
Description
Returns an audio file (MPEG) or markup of the spoken Finnish word/phrase.
Input Parameters
term(string, required): The word/phrase to speak.
lang(string, required): Language of term, MUST be fi.
returnmarkup(string, optional): If "1", returns timing markup instead of audio.
voice(string, optional): Specifies the voice to use (check available voices). If not provided, uses the default voice.
Output
If returnmarkup=1: JSON object containing timing markup.
Otherwise: Audio file (MPEG). Set Content-Type header to audio/mpeg.
Example
/speak?term=tervetuloa&lang=fi (returns audio)
/speak?term=tervetuloa&lang=fi&returnmarkup=1 (returns JSON markup)
Finnish to English
Path
/finnishtoenglish
Description
Translates a Finnish word/phrase to English.
Input Parameters
term(string, required): The Finnish word/phrase.
Output
A JSON object containing the translation. Returns an empty object {} if no results are found. The structure depends on the translation.
Example
/finnishtoenglish?term=hyvää huomenta
English to Finnish
Path
/englishtofinnish
Description
Translates an English word/phrase to Finnish.
Input Parameters
term(string, required): The English word/phrase.
Output
A JSON object containing the translation. Returns an empty object {} if no results are found. The structure depends on the translation.
Example
/englishtofinnish?term=good morning
Suggest
Path
/suggest
Description
Returns word suggestions for a given Finnish term.
Input Parameters
term(string, required): The Finnish word to get suggestions for.
Output
A JSON array of suggested words. Returns an empty array [] if no results are found.
Example
/suggest?term=kirj
Search
Path
/search
Description
Searches for dictionary entries based on either Finnish or English.
Input Parameters
finnish(string, optional): Finnish term to search for.
english(string, optional): English term to search for.
Output
A JSON object containing the search results. Returns an empty object {} if no results are found. The structure depends on the search.
Note: Must provide either finnish or english, but not both.
Example
/search?finnish=kissa
/search?english=cat
Dictionary
Path
/dict
Description
Looks up dictionary entries for a given term in a specified language.
Input Parameters
term(string, required): The term to search for.
lang(string, required): The language of the term ("fi" for Finnish, "en" for English).
Output
A JSON object containing the dictionary results and suggestions. Returns an empty object {} if no results are found.
Example
/dict?term=koira&lang=fi
Ninja
Path
/ninja
Description
Executes various commands, including translation, conjugation, and dictionary lookups, combined into one endpoint.
Options
Supported Commands:
Input Parameters
command(string, required): The command to execute, along with any necessary terms, separated by spaces (e.g., "fi-en hello", "kotus talo").
Output
A JSON object containing the result of the command.
Example
/ninja?command=fi-en talo
/ninja?command=kotus auto
/ninja?command=rc menen
Tiny Ninja
Path
/tinyninja
Description
Executes simple commands using the Tiny Ninja module.
Input Parameters
command(string, required): The command to execute. Limited to 50 characters.
Output
Plain text result of the command.
Example
/tinyninja?command=en dog
How To Say
Path
/howtosay
Description
Looks up how to say term.
Input Parameters
term(string, required): Term to lookup.
Output
A JSON object containing the howtosay result.
Example
/howtosay?term=car
Mini Dictionary
Path
/minidict
Description
Performs a dictionary lookup between English and Finnish.
Input Parameters
word(string, required): The word to translate.
direction(string, required): The translation direction: "en-fi" (English to Finnish) or "fi-en" (Finnish to English).
Output
A JSON object containing the translation.
Example
/minidict?word=house&direction=en-fi
Readable Text
Path
/readabletext
Description
Makes text more readable by hyphenating words.
Options
level (number, optional): The output level (1, 2, or 3). Defaults to 3.
Input Parameters
text(string, required): The text to be processed.
Output
A JSON object containing the readable version of the text.
Example
/readabletext?text=Mennään kotiin
/readabletext?text=Mennään kotiin&level=1