FreeDict API

FreeDict API

Overview

The FreeDict API is a statically generated resource, providing information about all available dictionaries, including name, headword count, maintainer, download links and checksums of the downloads. It comes in two flavours: XML and JSON. Most of the FreeDict tooling uses the XML version, but new projects are free to choose whatever version. The API allows retrieving information about the dictionaries, their meta data and their releases (with download links).

Mount Point

You can retrieve the API file from either

https://freedict.org/freedict-database.xml

or

https://freedict.org/freedict-database.json

These are CORS-enabled, so that you can retrieve it across domains.

API Structure

The following sections will explain the the general structure of the XML file. The JSON format is discussed further below, but is basically a one-to-one translation from the XML file.

The XML file is encoded in UTF-8 and contains a root Element called FreeDictDatabase. The dictionaries are listed below this elements in Dictionary nodes. Each Dictionary may additionally contain Release nodes.

Dictionary

The dictionary element represents one source dictionary from FreeDict. It is independent from the underlying format (in fact, all dictionaries are encoded in TEI XML). A dictionary is identified by its name (attribute name), which is a hyphen-separated string of two ISO 639 codes. For instance, the Latin-German dictionary would be identified by `name="lat-deu". All other attributes are listed below.

Attribute Overview

name	Required	Explanation
headwords	yes	number of headwords in the dictionary
edition	yes	version number in the format release.major.minor, major and minor are optional, but must be separated by a dot (see semantic versioning
date	yes	date in the format year-month-day (year 4 digits, month 2 digits, day 2 digits)
maintainer	yes	name of the maintainer or a String like "FreeDict - no maintainer assigned"
maintainer email	no	email address of maintainer; might be escaped
status	no	the state of the dictionary, e.g. "too small" or "big enough to be useful"
source URL	no	link to the upstream project, if applicable

Release

Each dictionary may have one or more releases. Each release has multiple, required attributes, listed in the table below.

name	Explanation
platform	target platform, e.g. dictd for a file intended for the dict server in a .tar.xz archive (try make list-platforms in a dictionary of your choice for an up-to-date list)
version	same format as edition of the Dictionary node, see [overview table](#dict_attributes, is a semantic version)
date	same format as for the Dictionary node, see overview table
size	size of the download, in bytes
size	size of the download, in bytes
checksum	SHA512 checksum of the downloadable file to validate its integrity after download

Validation / Schema

The API is build on a RELAX NG schema, which allows for validation of the produced XML file. It is located in the git repository at https://github.com/freedict/fd-dictionaries/blob/master/freedict-database.rng. If you compiled the latest API file using "make api" from the tools directory, you can use make api-validation to execute the validation.

JSON API

As mentioned before, the JSON API is a rough one-to-one mapping from the XML version. There is no root element, but a list/an array of dictionaries. Each dictionary object can have all the key → value pairs as the Dictionary node from the XML version.

Each dictionary object has an additional key called releases. This contains an array of objects, each representing a release. They are again a one-to-one mapping from the XML Release node.

Example:

[
  {
    "date": "2017-10-21",
    "edition": "0.7",
    "headwords": "38000",
    "maintainerName": "John Smith",
    "name": "abc-def",
    "releases": [
      {
        "URL": "https://example.com/downloads/abc-def-0.7.tar.gz",
        "date": "2017-10-21",
        "platform": "src",
        "size": "198178",
        "version": "0.7"
      },
      …
    ]  ,
    …
  }
]