Regionen

Endpoint: Regionen

Die Regions-Endpoints ermöglichen den Zugriff auf alle verfügbaren Regionen. Nutze die zurückgegebenen IDs für Filter in Matching-Anfragen und Förderprogramm-Suchen.

GET /api/v1/regions

Listet alle Regionen. Standardmäßig in hierarchischer Struktur (Kontinent → Land → Bundesland/Staat).

Scope erforderlich: grants:read

Query-Parameter

Parameter	Typ	Beschreibung
`flat`	String	Wenn `"true"`, wird eine flache Liste zurückgegeben
`type`	String	Filter nach Regionstyp: `continent`, `country`, `state`
`country_id`	UUID	Filter Bundesländer nach übergeordnetem Land

Beispiel-Request (hierarchisch)

curl -X GET "https://foerdermittelkompass.reflecta.org/api/v1/regions" \
  -H "Authorization: Bearer rfk_dein_token" \
  -H "Content-Type: application/json"

Beispiel-Response (hierarchisch)

{
  "regions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440100",
      "name": "Europa",
      "name_de": "Europa",
      "name_en": "Europe",
      "region_type": "continent",
      "countries": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440110",
          "name": "Deutschland",
          "name_de": "Deutschland",
          "name_en": "Germany",
          "region_type": "country",
          "states": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440111",
              "name": "Bayern",
              "name_de": "Bayern",
              "name_en": "Bavaria",
              "region_type": "state"
            },
            {
              "id": "550e8400-e29b-41d4-a716-446655440112",
              "name": "Berlin",
              "name_de": "Berlin",
              "name_en": "Berlin",
              "region_type": "state"
            }
          ]
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440120",
          "name": "Österreich",
          "name_de": "Österreich",
          "name_en": "Austria",
          "region_type": "country",
          "states": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440121",
              "name": "Wien",
              "name_de": "Wien",
              "name_en": "Vienna",
              "region_type": "state"
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "total_continents": 1,
    "total_countries": 3,
    "total_states": 18
  }
}

Beispiel-Request (nur Bundesländer eines Landes)

curl -X GET "https://foerdermittelkompass.reflecta.org/api/v1/regions?flat=true&type=state&country_id=550e8400-e29b-41d4-a716-446655440110" \
  -H "Authorization: Bearer rfk_dein_token"

Beispiel-Response (flache Liste)

{
  "regions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440111",
      "name": "Bayern",
      "name_de": "Bayern",
      "name_en": "Bavaria",
      "region_type": "state",
      "parent_id": "550e8400-e29b-41d4-a716-446655440110",
      "parent_name": "Deutschland"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440112",
      "name": "Berlin",
      "name_de": "Berlin",
      "name_en": "Berlin",
      "region_type": "state",
      "parent_id": "550e8400-e29b-41d4-a716-446655440110",
      "parent_name": "Deutschland"
    }
  ],
  "meta": {
    "total_count": 16,
    "by_type": {
      "continent": 1,
      "country": 3,
      "state": 18
    }
  }
}

GET /api/v1/regions/:id

Ruft Details einer einzelnen Region ab.

Scope erforderlich: grants:read

Path-Parameter

Parameter	Typ	Beschreibung
`id`	UUID	Region-ID

Beispiel-Request

curl -X GET "https://foerdermittelkompass.reflecta.org/api/v1/regions/550e8400-e29b-41d4-a716-446655440110" \
  -H "Authorization: Bearer rfk_dein_token"

Beispiel-Response (Land mit Bundesländern)

{
  "region": {
    "id": "550e8400-e29b-41d4-a716-446655440110",
    "name": "Deutschland",
    "name_de": "Deutschland",
    "name_en": "Germany",
    "region_type": "country",
    "parent": {
      "id": "550e8400-e29b-41d4-a716-446655440100",
      "name": "Europa",
      "name_de": "Europa",
      "name_en": "Europe",
      "region_type": "continent"
    },
    "subregions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440111",
        "name": "Bayern",
        "name_de": "Bayern",
        "name_en": "Bavaria",
        "region_type": "state",
        "parent_id": "550e8400-e29b-41d4-a716-446655440110",
        "parent_name": "Deutschland"
      }
    ]
  }
}

Verwendung für Matching

Die zurückgegebenen IDs, Namen oder Slugs können im organization_profile der Matching-Anfrage verwendet werden:

POST /api/v1/matching
{
  "organization_id": "partner-org-123",
  "organization_profile": {
    "name": "Kulturverein München e.V.",
    "description": "...",
    "regions": ["Bayern", "Berlin"]
  }
}

Hinweis: Du kannst Namen, Slugs oder UUIDs verwenden. IDs auf jeder Ebene sind möglich (Kontinent, Land, Bundesland). Bundesland-IDs liefern die präzisesten Ergebnisse.

Suche

Menu