FreeDict API - freedict/fd-dictionaries GitHub Wiki
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).
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.
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.
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 |
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 |
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.
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"
},
…
] ,
…
}
]