API-dokumentation for dansketaler.dk

Base URL

https://www.dansketaler.dk/api/v1

Endpoints

Liste over Taler

GET /speeches

Hent en liste over taler med valgfri filtrering og sortering.

Responsformater

API'et understøtter to responsformater:

JSON (standard)
CSV: Tilføj format=csv som query parameter

For at modtage svar i CSV-format, tilføj ?format=csv til URL'en.

Forespørgselsparametre

Parameter	Beskrivelse	Eksempel
q	Søgetekst på tværs af alle felter eller specificerede felter	`q=demokrati`
fields	Begræns søgning til specifikke felter. Flere værdier accepteres.	`fields=title,location`
tags	Filtrer efter tags. Kommasepareret liste.	`tags=demokrati,krig`
speaker_id	Filtrer taler efter specifik taler-ID	`speaker_id=1`
date	Filtrer efter dato eller datointerval i ISO-8601 format	`date=2023` eller `date=2023-01--2023-06`
sort	Sorter resultater efter specificeret felt	`sort=date`
mode	Formatering af transskription. Muligheder: plain (standard), html	`mode=html`
format	Responsformat. Muligheder: json (standard), csv	`format=csv`
page	Sidenummer til paginering	`page=2`
per_page	Antal resultater pr. side (standard: 10, maks: 50)	`per_page=25`

Feltparameterværdier: - title (titel) - location (sted) - language (sprog) - circumstances (omstændigheder) - transcription (transskription)

Sorteringsparameterværdier: - title (titel) - score (score, standard) - date (dato)

Tilstandsparameterværdier: - plain (almindelig, standard) - html

Datoparameterformat

Komplet dato: ÅÅÅÅ-MM-DD
År og måned: ÅÅÅÅ-MM
Kun år: ÅÅÅÅ
Måned og dag: MM-DD
Datointervaller: ÅÅÅÅ-MM--ÅÅÅÅ-MM eller ÅÅÅÅ--ÅÅÅÅ

Bemærk: Datointervaller skal indeholde årstal.

Hent Tale efter ID

GET /speeches/:id

Hent en specifik tale efter dens ID.

Svarformat

JSON Format

{
  "speeches": [
    {
      "id": number,
      "url": string,
      "created_at": string,
      "updated_at": string,
      "title": string,
      "language": string,
      "location": string,
      "circumstances": string,
      "date": {
        "iso_date": string,
        "day": number,
        "month": number,
        "year": number
      },
      "speakers": [
        {
          "id": number,
          "lastname": string,
          "firstname": string,
          "title": string,
          "born_year": number
        }
      ],
      "transcription": string|html,
      "tags": [
        {
          "name": string,
          "context": string
        }
      ]
    }
  ],
  "meta": {
    "current_page": number,
    "total_pages": number, 
    "total_count": number,
    "per_page": number
  }
}

CSV Format

CSV-responser indeholder følgende kolonner:

ID, Created, Updated, URL, Title, Language, Location, Circumstances, ISO date, Day, Month, Year, Speakers id, Speakers name, Speakers title, Speakers born year, Transcription, Tags, Tags context

Pagineringsinfo tilføjes som kommentarer i slutningen af CSV-filen:

# Pagination info
# Current page: 1 Total pages: 25 Total count: 1234 Per page: 50

Paginering

For både JSON og CSV-formater inkluderer API'et følgende pagineringsheadere:

X-Pagination-Current-Page: 1
X-Pagination-Total-Pages: 25
X-Pagination-Total-Count: 1234
X-Pagination-Per-Page: 50

Eksempler

List alle taler fra 2023 i CSV-format

GET /speeches?date=2023&format=csv

Søg efter taler om demokrati kun i titler

GET /speeches?q=demokrati&fields=title

Hent taler fra specifik taler sorteret efter dato

GET /speeches?speaker_id=1&sort=date

Filtrer taler med flere tags

GET /speeches?tags=demokrati,krig,fred

Hent taler fra første halvdel af 2023

GET /speeches?date=2023-01--2023-06

Hent taler med HTML-formatering

GET /speeches?mode=html

Hent side to med 25 resultater pr. side

GET /speeches?page=2&per_page=25

Fejlsvar

API'et returnerer standard HTTP-statuskoder:

200: Succes
400: Ugyldig Forespørgsel - Ugyldige parametre
404: Ikke Fundet - Tale eller ressource ikke fundet
500: Intern Serverfejl

Fejlsvar inkluderer en besked der beskriver fejlen.