{"openapi":"3.1.1","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Kartenwerk Geo API","summary":"Amtliche Geodaten aller 16 Bundesländer über einen gemeinsamen Katalog.","description":"Die Metadatenebene erschließt die amtlichen OGC-Kataloge aller 16 Bundesländer. Unterstützte und zulässige WFS-Ebenen können über ein kurzlebiges Ticket als GeoJSON abgefragt werden. Katalogeinträge sind keine Produktfreigabe; Lizenz, Herkunft und Warnungen bleiben in den Antworten sichtbar.","version":"1.0.0","contact":{"name":"Kartenwerk","email":"info@kartenwerk.co","url":"https://kartenwerk.co"}},"externalDocs":{"description":"Menschenlesbare Dokumentation mit vollständigem Schnellstart","url":"https://kartenwerk.co/api-docs"},"servers":[{"url":"https://kartenwerk.co/api/v1/geo","description":"Metadatenebene (API-Key als Bearer-Token)"}],"tags":[{"name":"Katalog","description":"Bundesländer, Dienste und veröffentlichte Ebenen."},{"name":"Zugriff","description":"Kurzlebige Tickets für unterstützte Feature-Abfragen."}],"security":[{"ApiKeyAuth":[]}],"paths":{"/regions":{"get":{"operationId":"listRegions","tags":["Katalog"],"summary":"Alle 16 Bundesländer und ihren Katalogumfang auflisten","description":"Liefert immer alle 16 Bundesländer. Zählwerte beschreiben den zuletzt erhobenen Upstream-Katalog, nicht die Kartenwerk-Produktverfügbarkeit.","parameters":[{"$ref":"#/components/parameters/LimitParameter"},{"$ref":"#/components/parameters/OffsetParameter"}],"responses":{"200":{"description":"Bundesländer und beobachteter Katalogumfang.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRegionsResponse"}}}},"400":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/regions/{state}/layers":{"get":{"operationId":"listRegionLayers","tags":["Katalog"],"summary":"Veröffentlichte Ebenen eines Bundeslands durchsuchen","parameters":[{"name":"state","in":"path","required":true,"description":"ISO-3166-2-Code des Bundeslands.","schema":{"$ref":"#/components/schemas/StateCode"}},{"name":"protocol","in":"query","schema":{"type":"string","enum":["wfs","wms","wcs","ogcapi"]}},{"name":"search","in":"query","description":"Freitextsuche in Ebenenname, Titel und Kurzbeschreibung.","schema":{"type":"string","minLength":2,"maxLength":100}},{"name":"include_attributes","in":"query","schema":{"type":"boolean","default":true}},{"name":"include_removed","in":"query","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/LimitParameter"},{"$ref":"#/components/parameters/OffsetParameter"}],"responses":{"200":{"description":"Gefundene Katalogebenen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListLayersResponse"}}}},"400":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/layers/{layer_id}":{"get":{"operationId":"getLayer","tags":["Katalog"],"summary":"Katalogmetadaten und Transport einer Ebene beschreiben","parameters":[{"$ref":"#/components/parameters/LayerIdParameter"}],"responses":{"200":{"description":"Ebenendetail mit absoluten Links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LayerDetailResponse"}}}},"400":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/tickets":{"post":{"operationId":"createFeatureTicket","tags":["Zugriff"],"summary":"Kurzlebiges Ticket für Feature-Abfragen ausstellen","description":"Das Ticket gilt fünf Minuten, für 1 bis 10 Ebenen und genau ein Ziel-CRS. Die Antwort liefert pro Ebene die absolute features_url; Clients müssen diese URL unverändert verwenden.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTicketRequest"}}}},"responses":{"200":{"description":"Ticket, Limits und absolute Feature-URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTicketResponse"}}}},"400":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Einheitlicher Fehlerumschlag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"Kartenwerk API-Key (ak_…)","description":"Langfristiger API-Key für die vier Metadaten-Endpunkte."},"FeatureTicketAuth":{"type":"http","scheme":"bearer","bearerFormat":"Kurzlebiges Kartenwerk Feature-Ticket (geoT1.…)","description":"Nur für POST-Anfragen an die zurückgegebene features_url."}},"schemas":{"StateCode":{"type":"string","enum":["DE-BW","DE-BY","DE-BE","DE-BB","DE-HB","DE-HH","DE-HE","DE-MV","DE-NI","DE-NW","DE-RP","DE-SL","DE-SN","DE-ST","DE-SH","DE-TH"],"example":"DE-NW"},"Crs":{"type":"string","enum":["EPSG:4326","EPSG:25832","EPSG:25833"],"default":"EPSG:4326"},"Pagination":{"type":"object","required":["total_matched","limit","offset","next_offset"],"properties":{"total_matched":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":50},"offset":{"type":"integer","minimum":0},"next_offset":{"type":["integer","null"],"minimum":0}}},"RegionSummary":{"type":"object","required":["state","state_name_de","service_count","layer_count","protocols","service_last_reachable_at"],"properties":{"state":{"$ref":"#/components/schemas/StateCode"},"state_name_de":{"type":"string"},"service_count":{"type":"integer","minimum":0},"layer_count":{"type":"integer","minimum":0},"protocols":{"type":"array","items":{"type":"string","enum":["wfs","wms","wcs","ogcapi"]}},"service_last_reachable_at":{"type":["string","null"],"format":"date-time"}}},"ListRegionsResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataEnvelope"},{"$ref":"#/components/schemas/Pagination"},{"type":"object","required":["regions"],"properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/RegionSummary"}}}}]},"Attribute":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":["string","null"]}}},"License":{"type":"object","required":["id","attribution","terms_url"],"properties":{"id":{"type":["string","null"]},"attribution":{"type":"string"},"terms_url":{"type":["string","null"],"format":"uri"}}},"PublishedUpstream":{"type":"object","required":["first_seen","last_seen","still_advertised","service_last_reachable_at"],"properties":{"first_seen":{"type":"string","format":"date-time"},"last_seen":{"type":"string","format":"date-time"},"still_advertised":{"type":"boolean"},"service_last_reachable_at":{"type":["string","null"],"format":"date-time"}}},"CatalogLayer":{"type":"object","required":["state","state_name_de","service_url","layer_name","service_protocol","service_title","service_version","service_provider","title","abstract","crs","bbox_wgs84","attributes","attributes_truncated","license","license_status","published_upstream"],"properties":{"state":{"$ref":"#/components/schemas/StateCode"},"state_name_de":{"type":"string"},"service_url":{"type":"string","format":"uri"},"layer_name":{"type":"string"},"service_protocol":{"type":"string","enum":["wfs","wms","wcs","ogcapi"]},"service_title":{"type":["string","null"]},"service_version":{"type":["string","null"]},"service_provider":{"type":["string","null"]},"title":{"type":["string","null"]},"abstract":{"type":["string","null"]},"crs":{"type":"array","items":{"type":"string"}},"bbox_wgs84":{"oneOf":[{"type":"null"},{"type":"array","minItems":4,"maxItems":4,"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]}]},"attributes":{"oneOf":[{"type":"null"},{"type":"array","items":{"$ref":"#/components/schemas/Attribute"}}]},"attributes_truncated":{"type":"boolean"},"license":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/License"}]},"license_status":{"type":"string","enum":["curated","unverified"]},"published_upstream":{"$ref":"#/components/schemas/PublishedUpstream"}}},"ListLayersResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataEnvelope"},{"$ref":"#/components/schemas/Pagination"},{"type":"object","required":["layers"],"properties":{"layers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogLayer"}}}}]},"LayerTransport":{"type":"object","required":["native_crs","available_target_crs","supports_bbox_filter","supports_attribute_filter","max_page_size","known_quirks"],"properties":{"native_crs":{"type":["string","null"]},"available_target_crs":{"type":"array","items":{"$ref":"#/components/schemas/Crs"}},"supports_bbox_filter":{"type":"boolean"},"supports_attribute_filter":{"type":"boolean"},"max_page_size":{"type":"integer","minimum":1,"maximum":10000},"known_quirks":{"type":"array","items":{"type":"object","required":["kind","note_de","note_en"],"properties":{"kind":{"type":"string"},"note_de":{"type":"string"},"note_en":{"type":"string"}}}}}},"LayerDetailResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataEnvelope"},{"type":"object","required":["layer_id","layer","transport","links"],"properties":{"layer_id":{"type":"string","pattern":"^geo1\\."},"layer":{"$ref":"#/components/schemas/CatalogLayer"},"transport":{"$ref":"#/components/schemas/LayerTransport"},"links":{"type":"object","required":["self","features"],"properties":{"self":{"type":"string","format":"uri"},"features":{"type":"string","format":"uri"}}}}}]},"CreateTicketRequest":{"type":"object","required":["layer_ids"],"properties":{"layer_ids":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","pattern":"^geo1\\."}},"target_crs":{"$ref":"#/components/schemas/Crs"}},"additionalProperties":false},"TicketLimits":{"type":"object","required":["max_features_per_page","max_bytes_per_response","max_requests","rate_limit_per_second","monthly_request_quota"],"properties":{"max_features_per_page":{"type":"integer","minimum":1,"maximum":10000},"max_bytes_per_response":{"type":"integer","minimum":1,"maximum":33554432},"max_requests":{"type":["integer","null"],"minimum":1},"rate_limit_per_second":{"type":["integer","null"],"minimum":1},"monthly_request_quota":{"type":["integer","null"],"minimum":1}}},"CreateTicketResponse":{"type":"object","required":["schema_version","token","expires_at","target_crs","layers","limits"],"properties":{"schema_version":{"const":1},"token":{"type":"string","pattern":"^geoT1\\."},"expires_at":{"type":"string","format":"date-time"},"target_crs":{"$ref":"#/components/schemas/Crs"},"layers":{"type":"array","items":{"type":"object","required":["layer_id","features_url"],"properties":{"layer_id":{"type":"string","pattern":"^geo1\\."},"features_url":{"type":"string","format":"uri","description":"Absolute URL; unverändert für die Feature-Abfrage verwenden."}}}},"limits":{"$ref":"#/components/schemas/TicketLimits"}}},"FeatureFilter":{"oneOf":[{"type":"object","required":["property","op","value"],"properties":{"property":{"$ref":"#/components/schemas/FeaturePropertyName"},"op":{"const":"eq"},"value":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["property","op","value"],"properties":{"property":{"$ref":"#/components/schemas/FeaturePropertyName"},"op":{"const":"like"},"value":{"type":"string"}},"additionalProperties":false},{"type":"object","required":["property","op","value"],"properties":{"property":{"$ref":"#/components/schemas/FeaturePropertyName"},"op":{"const":"in"},"value":{"type":"array","minItems":1,"items":{"type":"string"}}},"additionalProperties":false}]},"FeaturePropertyName":{"type":"string","pattern":"^[\\p{L}_][\\p{L}\\p{N}_.-]*$","description":"Ein einzelner, nicht qualifizierter XML-Attributname."},"FeatureRequest":{"type":"object","properties":{"bbox":{"type":"array","minItems":4,"maxItems":4,"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"bbox_crs":{"$ref":"#/components/schemas/Crs"},"filter":{"$ref":"#/components/schemas/FeatureFilter"},"target_crs":{"$ref":"#/components/schemas/Crs"},"limit":{"type":"integer","minimum":1,"maximum":10000,"default":1000},"cursor":{"type":"string","description":"Opaker next_cursor der vorherigen Seite."}},"dependentRequired":{"bbox":["bbox_crs"]},"additionalProperties":false},"FeatureResponse":{"type":"object","required":["schema_version","upstream_disclaimer","layer_id","state","service_url","layer_name","crs","retrieved_at","license","license_status","attribution","changed_data_notice","matched","returned","next_cursor","warnings","features"],"properties":{"schema_version":{"const":1},"upstream_disclaimer":{"type":"string"},"layer_id":{"type":"string","pattern":"^geo1\\."},"state":{"$ref":"#/components/schemas/StateCode"},"service_url":{"type":"string","format":"uri"},"layer_name":{"type":"string"},"crs":{"$ref":"#/components/schemas/Crs"},"retrieved_at":{"type":"string","format":"date-time"},"license":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/License"}]},"license_status":{"type":"string","enum":["curated","unverified"]},"attribution":{"type":["string","null"]},"changed_data_notice":{"$ref":"#/components/schemas/ChangedDataNotice"},"matched":{"type":"object","required":["count","reliability"],"properties":{"count":{"type":["integer","null"],"minimum":0},"reliability":{"type":"string","enum":["exact","at_least","unknown"]}},"allOf":[{"if":{"properties":{"reliability":{"const":"unknown"}},"required":["reliability"]},"then":{"properties":{"count":{"type":"null"}}}}]},"returned":{"type":"integer","minimum":0},"next_cursor":{"type":["string","null"]},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"}},"features":{"$ref":"#/components/schemas/FeatureCollection"}}},"ChangedDataNotice":{"type":"object","required":["applies","text_de","text_en","reasons"],"properties":{"applies":{"const":true},"text_de":{"const":"Daten verändert"},"text_en":{"const":"Data modified"},"reasons":{"type":"array","minItems":1,"items":{"type":"string","enum":["format_conversion","reprojection","spatial_filter","attribute_filter","pagination"]}}},"additionalProperties":false},"FeatureCollection":{"type":"object","required":["type","features"],"properties":{"type":{"const":"FeatureCollection"},"features":{"type":"array","items":{"type":"object","required":["type","geometry","properties"],"properties":{"type":{"const":"Feature"},"id":{"type":["string","number"]},"geometry":{"type":["object","null"]},"properties":{"type":["object","null"],"additionalProperties":true}}}},"crs":{"type":"object","description":"Nur bei projizierten Antworten vorhanden."}}},"Warning":{"type":"object","required":["kind","message_de","message_en"],"properties":{"kind":{"type":"string"},"message_de":{"type":"string"},"message_en":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"MetadataEnvelope":{"type":"object","required":["schema_version","upstream_disclaimer","catalog_last_harvest_at"],"properties":{"schema_version":{"const":1},"upstream_disclaimer":{"type":"string"},"catalog_last_harvest_at":{"type":["string","null"],"format":"date-time"}}},"ErrorEnvelope":{"type":"object","required":["schema_version","error"],"properties":{"schema_version":{"const":1},"error":{"type":"object","required":["kind","message_de","message_en","http_status","upstream_status","upstream_message","retry_after_seconds","circuit","request_id"],"properties":{"kind":{"type":"string"},"message_de":{"type":"string"},"message_en":{"type":"string"},"http_status":{"type":"integer","minimum":400,"maximum":599},"upstream_status":{"type":["integer","null"]},"upstream_message":{"type":["string","null"],"maxLength":500},"retry_after_seconds":{"type":["integer","null"],"minimum":0},"circuit":{"type":["object","null"]},"request_id":{"type":"string","pattern":"^req_[0-9a-f]{32}$"}}}}}},"parameters":{"LimitParameter":{"name":"limit","in":"query","description":"Seitengröße; Standard 20, Maximum 50.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},"OffsetParameter":{"name":"offset","in":"query","description":"Startposition; für die nächste Seite next_offset verwenden.","schema":{"type":"integer","minimum":0,"default":0}},"LayerIdParameter":{"name":"layer_id","in":"path","required":true,"description":"Opake Ebenen-ID aus einer Katalogantwort.","schema":{"type":"string","pattern":"^geo1\\."}}}},"x-kartenwerk-feature-request":{"summary":"WFS-Features über die absolute URL aus der Ticketantwort abrufen","method":"POST","urlSource":"CreateTicketResponse.layers[].features_url","security":[{"FeatureTicketAuth":[]}],"requestSchema":{"$ref":"#/components/schemas/FeatureRequest"},"responseSchema":{"$ref":"#/components/schemas/FeatureResponse"},"instructions":["Die features_url unverändert verwenden; den Datenebenen-Host nicht fest im Client speichern.","Das Ticket aus CreateTicketResponse.token als Bearer-Token senden.","Wenn bbox gesetzt ist, muss bbox_crs ausdrücklich angegeben werden."]}}