Developer API Dokumentation

Übersicht

Die geolokal.de API ermöglicht den programmatischen Zugriff auf unser Branchenverzeichnis. Die API verwendet REST-Prinzipien und kommuniziert über HTTPS mit JSON-Payloads.

Base URL

https://api.geolokal.de

Swagger / OpenAPI

Interaktive API-Dokumentation (falls aktiv):

https://api.geolokal.de/docs

Authentifizierung

Öffentliche Endpunkte (Suche, Firmenlisten) sind ohne Authentifizierung zugänglich. Für schreibende Operationen und erweiterte Funktionen ist ein API-Token erforderlich.

Header

Authorization: Bearer YOUR_API_TOKEN

Endpunkte

Firmen auflisten

Listet Firmen mit optionalen Filtern auf.

GET /api/companies

GET /api/companies?query=maler&city=münchen&limit=20

Response:
{
  "items": [
    {
      "id": 123,
      "name": "Maler Müller GmbH",
      "slug": "maler-mueller-gmbh",
      "category": "Maler",
      "city": "München",
      "postal_code": "80935",
      "street": "Beispielstraße",
      "house_number": "12",
      "phone": "+49 89 12345678",
      "email": "info@maler-mueller.de",
      "rating": 4.8,
      "review_count": 42
    }
  ],
  "total": 156,
  "page": 1,
  "limit": 20
}

Query Parameter

Parameter	Typ	Beschreibung
`query`	string	Suchbegriff (Name, Branche, Stichwort)
`city`	string	Stadt oder PLZ
`category`	string	Branchenkategorie
`limit`	integer	Anzahl Ergebnisse (max. 100, default: 20)
`page`	integer	Seitennummer für Pagination

Firma abrufen

Ruft Details einer einzelnen Firma ab.

GET /api/companies/:id

GET /api/companies/123

Response:
{
  "id": 123,
  "name": "Maler Müller GmbH",
  "slug": "maler-mueller-gmbh",
  "category": "Maler",
  "categories": ["Maler", "Lackierer", "Fassade"],
  "description": "Ihr Malerbetrieb in München...",
  "street": "Beispielstraße",
  "house_number": "12",
  "postal_code": "80935",
  "city": "München",
  "country": "DE",
  "phone": "+49 89 12345678",
  "email": "info@maler-mueller.de",
  "website": "https://maler-mueller.de",
  "opening_hours": {
    "mon": [{"open": "08:00", "close": "17:00"}],
    "tue": [{"open": "08:00", "close": "17:00"}]
  },
  "rating": 4.8,
  "review_count": 42,
  "logo_url": "https://...",
  "image_urls": ["https://..."]
}

Firma erstellen

Erstellt einen neuen Firmeneintrag. Erfordert Authentifizierung.

POST /api/companies

POST /api/companies
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "name": "Neue Firma GmbH",
  "category": "Elektriker",
  "street": "Musterstraße",
  "house_number": "1",
  "postal_code": "80935",
  "city": "München",
  "phone": "+49 89 98765432",
  "email": "info@neue-firma.de"
}

Response: 201 Created
{
  "id": 456,
  "slug": "neue-firma-gmbh",
  "message": "Firma erfolgreich erstellt"
}

Firma aktualisieren

Aktualisiert einen bestehenden Firmeneintrag.

PUT /api/companies/:id

PUT /api/companies/123
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "description": "Aktualisierte Beschreibung...",
  "phone": "+49 89 11111111"
}

Response: 200 OK
{
  "id": 123,
  "message": "Firma erfolgreich aktualisiert"
}

Firma löschen

Löscht einen Firmeneintrag. Erfordert entsprechende Berechtigung.

DELETE /api/companies/:id

DELETE /api/companies/123
Authorization: Bearer YOUR_API_TOKEN

Response: 200 OK
{
  "message": "Firma erfolgreich gelöscht"
}

Fehlerbehandlung

Die API verwendet Standard-HTTP-Statuscodes:

Status	Bedeutung
`200`	Erfolgreiche Anfrage
`201`	Ressource erfolgreich erstellt
`400`	Ungültige Anfrage (Validierungsfehler)
`401`	Nicht authentifiziert
`403`	Keine Berechtigung
`404`	Ressource nicht gefunden
`429`	Rate Limit überschritten
`500`	Serverfehler

Rate Limiting

Die API ist auf 100 Anfragen pro Minute pro IP-Adresse limitiert. Bei Überschreitung erhalten Sie einen 429 Too Many Requests Fehler.

Kontakt & Support

Bei Fragen zur API oder für erweiterte Zugriffsrechte kontaktieren Sie uns:

E-Mail: mail@geolokal.de
Telefon: 089 20571770

Hinweis

Die API befindet sich in aktiver Entwicklung. Endpunkte und Datenstrukturen können sich ändern. Für produktive Integrationen empfehlen wir, uns vorab zu kontaktieren.