API Dokumentation

API v1

Die API Version 1 entspricht der seit einigen Jahren bestehenden Schnittstellenspezifikation. Alle bisher angebundenen Partner:innen-Websites benutzen diese Version. Zwar wurde das zugrunde liegende Datenbanksystem Ende 2021 erneuert, jedoch wird die fortbestehende Verfügbarkeit der bis dato gültigen API durch einen Adapter abgesichert.

Host (empfohlen) » https://daten.nachhaltiges-sachsen.de/api/v1

Host (deprecated) » https://daten.nachhaltiges-leipzig.de/api/v1

----------

API v2 wird voraussichtlich im Laufe des 2. Quartals 2022 verfügbar.


Endpunkte für API v1

Angebote

Die Datenbank unterscheidet in folgende Angebotstypen via Attribut type

  1. Beratungsangebote (counseling)

  2. Bildungsangebote (education)

  3. Veranstaltungen (event)

  4. Projekte (project)

  5. Filialen (store)

Liste aller Angebote

» activities.json

Einzelnes Angebot

» activities/[id].json

Mögliche Filter als GET-Parameter; kombinierbar (AND)

type=[typeKey]
» activities.json?type=event

region_id=[id]
alle Angebote, welche einer Region aus regions.json zugeordnet sind
» activities.json?region_id=109

category_id=[id]
alle Angebote, welche mit einer Kategorie aus categories.json kategorisiert sind
» activities.json?category_id=5

goal_id=[id]
alle Angebote, welche mit einem Ziel aus goals.json kategorisiert sind
» activities.json?goal_id=67

timestamp[d-m-Y]
alle Veranstaltungen an diesem Datum
» activities.json?timestamp=02-04-2022

upcoming
alle Veranstaltungen ab heute
» activities.json?upcoming

upcoming[d-m-Y]
alle Veranstaltungen ab angegebenem Datum
» activities.json?upcoming=01-10-2022

text=[Suchbegriff:string]
alle Angebote, deren Titel oder Beschreibung dem Suchbegriff ähneln
» activities.json?text=demonstration

Organisationen

Trägerorganisation (auch Akteure genannt) von Angeboten referenziert via Attribut user

Liste aller Organisationen

» users.json

Einzelne Organisation

» users/[id].json

Regionen

Kategorisierung von Akteuren und Angeboten referenziert via Attribut region

Liste aller Regionen, z.B. Stadt Leipzig, Stadt Dresden, Vogtlandkreis

» regions.json

Hauptkategorien

Kategorisierung von Angeboten referenziert via Attribut categories | root_categories | first_root_category

Liste aller Hauptkategorien inkl. Unterkategorien, z.B. Stadt Leipzig, Stadt Dresden, Vogtlandkreis

» categories.json

Ziele

Kategorisierung bzw. Tagging von Angeboten referenziert via Attribut goals

Liste aller Ziele, z.B. Chancengerechtigkeit, Familienfreundlichkeit, lokale Wertschöpfung

» goals.json

Arten von Handelseinrichtungen

Kategorisierung von Angeboten referenziert via Attribut trade_types

Liste aller Arten von Handelseinrichtungen, z.B. Fachhandel, Supermarkt, Restaurant/Café

» trade_types.json

Handelskategorien

Kategorisierung von Angeboten referenziert via Attribut trade_categories

Liste aller Handelskategorien, z.B. Fairer Handel, Bio-Produkte, regionale Produkte

» trade_categories.json

Produkttypen

Kategorisierung von Akteuren und Angeboten referenziert via Attribut products

Liste aller Produkttypen, z.B. Gewürze, Kosmetik, Kunsthandwerk

» products.json

Orte

Mehrfach (wieder)verwendete Orte referenziert via Attribute location_id

Liste aller Orte, z.B. Thomaskirche

» locations.json

Einzelner Ort

» locations/[id].json


Bilddateien

Über eine URL referenzierte Bilddateien können in verschiedenen Größen angefordert werden. Dazu können der Bild-URL folgende GET-Parameter angehängt werden:

width : maximale Breite in Pixeln

height: maximale Höhe in Pixeln

Die Bild-URL in Originalgröße erhält man z.B. über die Attribute image_url_base bei Angeboten oder via organization_logo_url_base bei Organisationen. Diese kann als Basis für die Ergänzung von Parametern für die gewünschte Bildgröße verwendet werden.

Beispiel:

Bild in Originalgröße via Attribut organization_logo_url_base aus users.json

» https://daten.nachhaltiges-sachsen.de/media/2374/duw_logo_farbe_text_no_cutout.png

Dimensioniertes Bild über angehängte GET-Parameter

» https://daten.nachhaltiges-sachsen.de/media/2374/duw_logo_farbe_text_no_cutout.png?width=200&height=200

Breite und Höhe des Bildes sind jeweils auf max. 200 Pixel dimensioniert, d.h. ein Querformat-Bild ist max. 200 Pixel breit bzw. ein Hochformat-Bild ist max. 200 Pixel hoch