BUILD WITH SOMALI

Developers

Read published language data, download open formats, and keep attribution with every record.

Public data access

These read-only endpoints do not require sign-in or an API key. This is a prototype service, without a production availability guarantee.

Published entries/api/export?format=jsonJSON Published entries/api/exportJSONL Technology planning list/api/technologyDraft JSON Technology planning list/api/technology?format=jsonlDraft JSONL

JavaScript

const params = new URLSearchParams({
  q: 'home', category: 'translation',
  page: '1', limit: '25'
});
const response = await fetch('/api/v1/entries?' + params);
const result = await response.json();
if (!response.ok) throw new Error(result.error.message);
console.log(result.data, result.pagination);

On another origin, replace the relative URL with this application origin. Cross-origin browser requests require an explicitly allowed origin. Server-side clients can use the API directly. Never include workspace cookies or credentials.

Version 1 API

GET /api/v1/entries returns only openly licensed published entries, never workspace drafts or the untranslated planning list. No sign-in or key is required.

q: Search term and translation, up to 100 characters. Letters, numbers, spaces, apostrophes and hyphens only; matching ignores case.
category: vocabulary, translation or grammar.
dialect: Exact dialect name, up to 100 characters.
page / limit: Page starts at 1 (maximum 10000). Default page size 25, maximum 100. Results sort by newest publication then identifier. Pagination is a live view; use frozen releases for reproducible datasets.

Response

{ "api_version": "v1", "status": "published", "data": [],
  "pagination": { "page": 1, "limit": 25, "total": 0,
    "total_pages": 0, "has_next": false } }

Each data record contains id, category, term (Somali), translation, notes, source, license, dialect, version and created_at. Preserve source and licensing information when reusing data.

Errors

400 invalid_parameters: invalid, unknown or repeated query parameters. 503 unavailable: published data could not load; retry later. Errors use { "error": { "code": "…", "message": "…" } }. An empty successful response is 200, not an error. Other HTTP methods are not supported.

Draft planning downloads are separate resources, not part of the published v1 API. Public endpoints have a 60-request/minute per-process backstop (shared unless a trusted proxy is configured). 429 responses include Retry-After in seconds. Distributed edge limits are required before production launch.

Allowed browser origins receive CORS headers for read-only access, without credentials. Unlisted browser origins receive 403 origin_rejected. Check service health for current database reachability; this is a live check, not historical uptime or an SLA.

Data contract

Published records

Records include identifiers, category, term, translation, notes, source, license, dialect and version. JSON downloads return an array; JSONL has one record per line. No published data means an empty array or empty JSONL file.

Draft terminology

The planning list uses English terms, domains and a needs_translation status. somali: null means no translation has been provided. It is not a reviewed dictionary.

Licensing

Check the license and source of each record. CC-BY records require attribution. Permission-pending submissions are excluded from published exports; software licensing does not grant rights to third-party text.

Versioned releases

Open release history. JSON and JSONL contain the same frozen records. Keep the licensing manifest alongside either file. SHA256SUMS lists hashes of the exact UTF-8 download bytes; verify with sha256sum -c or PowerShell Get-FileHash -Algorithm SHA256.

Release downloads are frozen snapshots, with a separate licensing manifest. The catalog endpoint /api/public lists published entries, articles and up to 100 releases. The catalog loads at most 500 entries and 500 articles; use the export for the full published-entry download.