REST-API

Voraussetzungen

• Die Kunden-API und API-Keys gibt es ab dem Tarif Starter (siehe Preise). In anderen Tarifen antwortet die API mit 403 und error: "plan_limit".
• Den Key legen Sie in der App unter API & Webhooks → API-Key erstellen an. Dafür brauchen Sie das Recht, die API zu verwalten (z. B. Inhaber und Administratoren).
• Der Key wird nur einmal angezeigt. Wir speichern ihn nur als Hash. Behandeln Sie ihn wie ein Passwort und widerrufen Sie ihn, wenn Sie ihn nicht mehr brauchen.

Auf derselben Seite der App finden Sie eine fertige Postman-Sammlung und eine OpenAPI-Datei zum Herunterladen.

Anmeldung

Basis-Adresse: https://app.my-store-locator.com/api/v1/ext

Schicken Sie den Key im Header Authorization (oder alternativ in X-Api-Key):

curl https://app.my-store-locator.com/api/v1/ext/me \
  -H "Authorization: Bearer msl_live_IHR-KEY"

{ "ok": true, "key": "Warenwirtschaft", "scopes": ["locations:read", "locations:write"] }

Die API ist für Server-zu-Server-Aufrufe gedacht. Sie sendet keine CORS-Header - aus dem Browser einer Website heraus funktioniert sie nicht, und der Key gehört auch nicht in den Code einer Website.

Berechtigungen

Beim Anlegen wählen Sie, was der Key darf:

Fehlt die Berechtigung, kommt 403 mit error: "scope".

Endpunkte

Standorte abrufen

curl "https://app.my-store-locator.com/api/v1/ext/locations?city=Frankfurt&limit=50" \
  -H "Authorization: Bearer msl_live_IHR-KEY"

Ohne sort ist die Antwort nach id sortiert:

{
  "data": [
    {
      "id": 1003,
      "name": "Filiale Frankfurt Mitte",
      "street": "Zeil 10",
      "zip": "60313",
      "city": "Frankfurt am Main",
      "state": "Hessen",
      "country": "DE",
      "lat": 50.1144,
      "lon": 8.6843,
      "phone": "069 123456",
      "email": "frankfurt@example.com",
      "website": "https://example.com/frankfurt",
      "manager": "",
      "description": "",
      "timezone": "Europe/Berlin",
      "hours": { "mo": ["09:00", "18:00"], "sa": ["10:00", "14:00"], "su": null },
      "specialDays": [{ "date": "2026-12-24", "open": "09:00", "close": "13:00", "label": "Heiligabend" }],
      "services": ["Parkplatz"],
      "tags": ["Neu"],
      "custom": {},
      "categoryId": 12,
      "status": "st_active_7",
      "created": "2026-10-20T08:12:00.000Z",
      "updated": "2026-10-24T15:40:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Für einen regelmäßigen Abgleich merken Sie sich den Zeitpunkt des letzten Laufs und fragen beim nächsten Mal mit updatedSince nur die Änderungen ab.

Standort anlegen und ändern

curl -X POST https://app.my-store-locator.com/api/v1/ext/locations \
  -H "Authorization: Bearer msl_live_IHR-KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Filiale Köln", "street": "Hohe Str. 1", "zip": "50667", "city": "Köln", "country": "DE",
        "hours": { "mo": ["09:00", "13:00", "14:00", "18:00"] } }'

• Pflicht: name und city (oder zip). country ist ohne Angabe DE.
• Koordinaten: Ohne lat und lon sucht unser Kartenserver die Adresse selbst heraus.
• Karten: Der neue Standort kommt wie in der App auf alle veröffentlichten Karten. Mit "maps": [4, 7] legen Sie die Karten selbst fest.
• Status: Ohne status gilt der erste Status Ihrer Liste.
• Antwort: 201 mit dem neuen Standort.

Weitere Felder: categoryId, status, state, phone, email, website, manager, description, timezone, hours, specialDays, services, tags, custom, photo.

• hours: Tage mo bis su, je eine Liste mit bis zu vier Uhrzeiten HH:MM (Öffnen, Schließen, bei Mittagspause noch einmal Öffnen, Schließen) oder null für geschlossen.
• specialDays: Liste mit date (JJJJ-MM-TT), open, close, optional open2, close2 und label.
• services, tags: Listen mit Texten.
• custom: Werte Ihrer eigenen Felder, Schlüssel = ID des Feldes. Unbekannte Felder werden ignoriert.
• photo: eine https-Adresse; wir laden das Bild und speichern es selbst, damit die Karte keine fremden Server aufruft.

PATCH /locations/{id} ändert nur die Felder, die Sie schicken. DELETE /locations/{id} archiviert den Standort wie „Löschen“ in der App und antwortet mit { "id": 1003, "deleted": true }.

Schreibende Aufrufe laufen durch dieselben Prüfungen wie die App: Tarifgrenzen, Pflichtfelder, gültige Werte. Im Protokoll des Kontos stehen sie als „API-Key …“ mit dem Namen des Keys.

Limits und Fehler

• 600 Aufrufe pro Minute und Key. Darüber: 429 mit Retry-After.
• Antworten werden nicht zwischengespeichert (Cache-Control: no-store).

Die message ist deutsch. Mit dem Header X-MSL-Lang: en kommen die meisten Meldungen auf Englisch.

Öffentliche Endpunkte einer Karte

Diese Endpunkte braucht die Karte selbst. Sie funktionieren ohne Key, nur für veröffentlichte Karten aktiver Konten, und sind pro IP-Adresse begrenzt. Der Token ist derselbe wie im Einbettungscode.

Auch diese Endpunkte senden keine CORS-Header. Jeder Abruf der Karte zählt in Ihrer Statistik als Kartenaufruf. Wenn Sie Kartendaten regelmäßig in ein eigenes System übernehmen möchten, nehmen Sie besser die Kunden-API.

Webhooks per API

Plattformen wie Zapier, Make und n8n legen Webhooks selbst an und entfernen sie wieder. Der API-Key braucht dafür die Berechtigung webhooks:write.

Mögliche Ereignisse: location.created, location.updated, location.deleted, map.published, lead.created, import.finished. Die Antwort auf POST enthält einmalig das secret zum Prüfen der Signatur. Details unter Webhooks.

OpenAPI-Datei

Die vollständige Beschreibung der API liegt öffentlich unter https://app.my-store-locator.com/api/v1/ext/openapi.json (Deutsch mit ?lang=de). Sie lässt sich direkt in Postman, Swagger UI oder die Importfunktion vieler Plattformen laden.