Area Service

Der Area Service stellt eine REST API zum Abfragen von Grenzen und Gebieten anhand geografischer Koordinaten oder OpenStreetMap-IDs bereit. Die API unterstützt die Formate JSON und GeoJSON.

Ebenen

Die Tabelle zeigt die typische Verwendung der admin_level-Werte in OpenStreetMap für verschiedene Verwaltungsebenen. Die genaue Bedeutung kann jedoch je nach Land und Region variieren. Die Werte 2 bis 11 werden am häufigsten verwendet, manche Länder definieren jedoch zusätzliche Ebenen. Die länderspezifische Bedeutung der admin_level-Werte können Sie in dieser Tabelle nachschlagen.

Ebene	Beschreibung
0	Eindeutige SmartMaps-Ebene für Postleitzahlen
2	Staatsgrenzen
3	Bundesländer, Provinzen, Regionen (1. Ebene)
4	Landkreise, Bezirke, Regionen (2. Ebene)
5	Gemeinden, Städte, Metropolregionen
6	Townships, Boroughs, Stadtbezirke, Unterkommunen
7	Stadtteile, Viertel, Dörfer, Weiler
8	Stadtblöcke, Wards, Unterbezirke, Ortschaften, Siedlungen
9	Statistische Bezirke, Postleitzahlgebiete, Wahlbezirke
10	Blöcke, Viertel, Nachbarschaften, Zählbezirke
11	Wahlbezirke, Schulbezirke, Pfarreien, Zählbezirke

Endpunkte

Grenzen an einem Punkt abrufen

Ruft die Grenzen und Gebiete an einem bestimmten geografischen Punkt ab.

POST https://area.smartmaps.cloud/api/v2/Boundaries/point

GET  https://area.smartmaps.cloud/api/v2/Boundaries/point

Parameter:

Parameter	Erforderlich	Typ	Beschreibung
`apiKey`	Ja	string	API-Key zur Authentifizierung
`channel`	Nein	string	Kanal für die Anfrage
`level`	Ja	integer	Verwaltungsebene der Grenzen (z. B. 2 für Länder)
`latitude`	Ja	number	Breitengrad des Punkts
`longitude`	Ja	number	Längengrad des Punkts
`isoCountries`	Nein	string	Kommagetrennte Liste von ISO-Ländercodes zur Filterung
`isoLanguages`	Nein	string	Kommagetrennte Liste von ISO-Sprachcodes für die Ergebnisse
`reduceGeometry`	Nein	number	Faktor zur Reduzierung der Genauigkeit der Geometrien (0-1)
`zoom`	Nein	integer	Zoomstufe zur Bestimmung des Detailgrads der Geometrien

Der Anfragetext muss ein JSON-Objekt mit einem points-Array sein, das die abzufragenden Punkte enthält.

Beispiel für den POST-Anfragetext

{
  "isoCountries": [
    "string"
  ],
  "reduceGeometry": 0,
  "isoLanguages": [
    "string"
  ],
  "zoom": 0,
  "level": 0,
  "points": [
    {
      "latitude": 0,
      "longitude": 0
    }
  ]
}

Antwort:

Die Antwort ist eine GeoJSON-FeatureCollection, die die Grenzen und Gebiete an den angegebenen Punkten enthält.

Grenzen in einem Rechteck abrufen

Ruft die Grenzen und Gebiete innerhalb eines rechteckigen Bereichs ab.

POST https://area.smartmaps.cloud/api/v2/Boundaries/rectangle

GET https://area.smartmaps.cloud/api/v2/Boundaries/rectangle

Parameter:

Parameter	Erforderlich	Typ	Beschreibung
`apiKey`	Ja	string	API-Key zur Authentifizierung
`channel`	Nein	string	Kanal für die Anfrage
`level`	Ja	integer	Verwaltungsebene der Grenzen
`isoCountries`	Nein	string	Kommagetrennte Liste von ISO-Ländercodes zur Filterung
`isoLanguages`	Nein	string	Kommagetrennte Liste von ISO-Sprachcodes für die Ergebnisse
`reduceGeometry`	Nein	number	Faktor zur Reduzierung der Genauigkeit der Geometrien (0-1)
`zoom`	Nein	integer	Zoomstufe zur Bestimmung des Detailgrads der Geometrien

Der Anfragetext muss ein JSON-Objekt mit einer boundingBox-Eigenschaft sein, die die Koordinaten des Rechtecks enthält.

Beispiel für den POST-Anfragetext

{
  "isoCountries": [
    "string"
  ],
  "reduceGeometry": 0,
  "isoLanguages": [
    "string"
  ],
  "zoom": 0,
  "level": 0,
  "boundingBox": {
    "northEast": {
      "latitude": 0,
      "longitude": 0
    },
    "southWest": {
      "latitude": 0,
      "longitude": 0
    }
  }
}

Antwort:

Die Antwort ist eine GeoJSON-FeatureCollection, die die Grenzen innerhalb des angegebenen Rechtecks enthält.

Grenzen für eine OSM-ID abrufen

Ruft die Grenzen und Gebiete für eine OpenStreetMap-ID ab.

POST https://area.smartmaps.cloud/api/v2/Boundaries/osmid

Parameter:

Parameter	Erforderlich	Typ	Beschreibung
`apiKey`	Ja	string	API-Key zur Authentifizierung
`channel`	Nein	string	Kanal für die Anfrage
`osmid`	Ja	integer	OpenStreetMap-ID
`isoCountries`	Nein	string	Kommagetrennte Liste von ISO-Ländercodes zur Filterung
`isoLanguages`	Nein	string	Kommagetrennte Liste von ISO-Sprachcodes für die Ergebnisse
`reduceGeometry`	Nein	number	Faktor zur Reduzierung der Genauigkeit der Geometrien (0-1)
`zoom`	Nein	integer	Zoomstufe zur Bestimmung des Detailgrads der Geometrien
`latitude`	Nein	number	Breitengrad für den Mittelpunkt der Geometrien

Beispiel für den POST-Anfragetext

{
  "isoCountries": [
    "string"
  ],
  "reduceGeometry": 0,
  "isoLanguages": [
    "string"
  ],
  "zoom": 0,
  "osmids": [
    0
  ],
  "latitude": 0
}

Antwort:

Die Antwort ist eine GeoJSON-FeatureCollection, die die Grenzen für die angegebene OSM-ID enthält.

Datenmodell

Die API-Antworten enthalten GeoJSON-FeatureCollections mit den folgenden Eigenschaften:

type: Typ des GeoJSON-Objekts ("FeatureCollection")
bbox: Bounding Box der Grenzen
features: Array mit den einzelnen Grenzen und Gebieten
type: Typ des Features ("Feature")
geometry: Geometrie der Grenze als GeoJSON-Objekt
properties: Zusätzliche Eigenschaften wie Namen und Codes der Grenze

Für jede Grenze werden, sofern verfügbar, die Namen in verschiedenen Sprachen, der ISO-Code des zugehörigen Landes und eine Postleitzahl zurückgegeben.

Swagger

Weitere detaillierte Informationen zu den Antwortstrukturen finden Sie in der vollständigen Swagger-Dokumentation.

Sie können die OpenAPI-Definition (https://area.smartmaps.cloud/swagger/v2/swagger.json) auch direkt in Postman, Insomnia oder ähnliche API-Clients importieren.