Ergänzende APIs
Alle unterstützenden API-Endpunkte mit cURL-, Python- und Node-Beispielen: Länder, Bundesländer, Unterkategorienkatalog und Plattformen Ihres Tarifs.
Die unterstützenden Endpunkte stellen die drei Referenzkataloge bereit, anhand derer der Rest der API Eingaben validiert: welche Länder und Bundesländer unterstützt werden, welche Geschäftskategorien existieren und welche Plattformverzeichnisse Ihr Tarif abdeckt. Alle drei sind schreibgeschützt, nicht paginiert und geben jeweils den vollständigen Datensatz zurück. Daher reicht ein Read (Lesezugriff)-Schlüssel aus, und Caching ist wichtiger als Paginierung.
Endpunkte im Überblick
Unterstützte Länder und Bundesländer auflisten
GET /countries
Gibt den vollständigen Katalog unter data.supportedCountries zurück. Jedes Land enthält einen ISO-Code, einen base64-kodierten id, einen numerischen databaseId, ein states-Array, dessen Einträge eigene ISO-Codes haben, sowie drei Adresskennzeichen: hasCity (Stadt erforderlich), stateRequired (Bundesland erforderlich und anhand von states geprüft) und hasPostalCode (das Land verwendet Postleitzahlen). Für ein Land ohne Unterteilung wird ein leeres states-Array zurückgegeben.
Parameter
Dieser Endpunkt akzeptiert keine Parameter. Er gibt immer den vollständigen Datensatz zurück.
curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "supportedCountries": [ { "databaseId": 13, "hasCity": true, "id": "Q291bnRyeToxMw==", "iso": "AU", "name": "Australia", "states": [ { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" }, { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" } ] }, { "databaseId": 17, "hasCity": true, "id": "Q291bnRyeToxNw==", "iso": "BE", "name": "Belgium", "states": [] } ] }}Die beiden iso-Felder enthalten die Werte, die Sie benötigen. Der iso eines Landes wird beim Erstellen und Aktualisieren zu countryIso, und der iso eines Bundeslands wird zu stateIso. Wenn Sie beide vor einem Schreibvorgang anhand dieser Liste validieren, können Sie statt eines serverseitigen 400 eine verständliche Meldung in Ihrem eigenen Formular anzeigen.
Unterkategorien auflisten
GET /sub-categories
Gibt unter data.subcategories etwa 6.000 Kategoriedatensätze in einem einzigen, nicht paginierten Array zurück. Mit dieser Abfrage ermitteln Sie für einen Ihnen als Freitext bekannten Geschäftstyp die numerische id, die für einen Schreibvorgang für einen Standort erforderlich ist.
Parameter
Keine. Bei jedem Aufruf wird der gesamte Katalog zurückgegeben.
curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "subcategories": [ { "databaseId": 4589, "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==", "key": "3d-printing-service", "name": "3D printing service", "primary": true } ] }}Jeder Datensatz enthält fünf Felder. Welches Sie verwenden, hängt davon ab, wo der Wert eingesetzt wird.
Ein Standort akzeptiert eine primäre Kategorie in subCategoryId und bis zu 9 weitere in additionalCategoryIds.
Plattformen des Tarifs auflisten
GET /plan-sites
Gibt unter data.planSites alle Plattformverzeichnisse zurück, die im Tarif Ihres Kontos enthalten sind. Dies ist die maßgebliche Liste numerischer Plattform-IDs, und nur hier aufgeführte IDs sind an anderen Stellen der API gültig.
Parameter
Keine. Die Antwort ist auf den Tarif Ihres Kontos beschränkt.
curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "planSites": [ { "id": 1, "name": "Google Maps", "url": "maps.google.com", "supportedCountries": ["US", "CA", "IN", "GB", "DE"], "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"] }, { "id": 184, "name": "Facebook", "url": "facebook.com", "supportedCountries": ["US", "CA", "IN", "GB", "DE"], "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"] } ] }}Die beiden Länder-Arrays beantworten unterschiedliche Fragen. supportedCountries gibt an, wo die Plattform überhaupt einen Eintrag akzeptiert. Filtern Sie daher nach dem countryIso Ihres Standorts, bevor Sie eine Plattform zur Auswahl anbieten. hideAddressSupportedCountries gibt an, wo die Plattform eine ausgeblendete Adresse berücksichtigt, was ein Unternehmen mit Einzugsgebiet benötigt. Beide Arrays können 50 oder mehr Codes enthalten; das obige Beispiel ist gekürzt.
Plattform-IDs sind stabil, und es lohnt sich, sie zu kennen: 1 steht für Google Maps und 184 für Facebook, die beiden Plattformen, auf die die meisten Verbindungsabläufe ausgerichtet sind.
Aktionslinks für Standorte
Kein eigenständiger Endpunkt. Aktionslinks für Standorte sind die Google-Schaltflächen wie Order online (online bestellen), Reserve a table (tisch reservieren) und Book an appointment (termin buchen). Die Plattform verwaltet sie als Feld am Standort statt als separate Ressource. Sie legen sie beim Erstellen und Aktualisieren über das Array placeActionLinks fest und lesen sie über einen beliebigen Endpunkt zum Lesen von Standorten wieder aus.
Jeder Eintrag benötigt placeActionType und uri, unterstützt ein optionales Flag isPreferred mit höchstens einem bevorzugten Link pro Typ und akzeptiert bei Aktualisierungen für action den Wert add oder delete. Die gültigen Typen, die Löschregeln und das Synchronisierungsverhalten finden Sie unter Aktionslinks für Standorte.
Fehler, die auftreten können
Keiner dieser Endpunkte führt Schreiboperationen aus, daher wird hier bei Verwendung eines Read-Schlüssels niemals SY90016 zurückgegeben. Die vollständige Liste finden Sie unter Fehlercodes.
Nächste Schritte
- Länder und Kategorien nachschlagen: die aufgabenorientierte Anleitung, die den Übergang zum Erstellen eines Standorts Schritt für Schritt erläutert.
- Einen Standort hinzufügen: Hier werden
countryIsoundsubCategoryIdverwendet. - Fehler in Einträgen finden und beheben: verwendet die im Tarif enthaltenen Websites, um eine fehlende Plattform von einer fehlerhaften zu unterscheiden.
- Referenz der unterstützenden APIs mit der vollständigen Feldliste für alle drei Endpunkte.