Für Programme und Assistenten

Die Register-API

Format holdmark-expediente/1.0 · Version v1

Alles, was holdmark über einen Shop veröffentlicht, lässt sich aus einem Programm heraus lesen: ohne Schlüssel, ohne Anmeldung und kostenlos. Es sind dieselben Angaben, die jeder auf der Seite dieses Shops sieht, in einem Format, das eine Maschine versteht.

So wird sie benutzt

Eine Anfrage, ein Shop, über seine Domain:

curl https://holdmark.org/api/v1/tiendas/tienda-ejemplo.com

Die Domain kann mit www. oder ohne angegeben werden, in Groß- oder Kleinschreibung: Die Antwort ist dieselbe. Um zu erfahren, was es gibt und wie alles heißt, beschreibt sich die API selbst:

curl https://holdmark.org/api/v1

Was sie zurückgibt

Die vollständige Akte des Shops. Jeder Fakt kommt mit seiner Antwort, seiner Quelle und dem zugehörigen Zeitraum:

{
  "format": "holdmark-expediente/1.0",
  "merchant": { "domain": "tienda-ejemplo.com", "platform": "shopify" },
  "facts": {
    "delivers_orders": { "answer": "yes", "value": 0.99, "source": "carrier" },
    "refunds_money":   { "answer": "yes", "source": "payment_processor" },
    "bank_claims":     { "value": 2, "unit": "per_1000_orders" },
    "verified_orders": { "band": "+50.000" }
  },
  "not_measured": ["customer_service", "product_quality", "opinions"],
  "rounding": "against the merchant"
}

Wie die Zahlen zu lesen sind

• Gerundet wird immer zulasten des Shops: Günstiges wird abgerundet, Ungünstiges aufgerundet. Ein Shop steht nie besser da, als er ist.
• Volumen in Stufen: nie die genaue Zahl der Bestellungen, nur die Stufe („über 50.000“).
• Jede Zahl mit ihrem Zeitraum: Bankreklamationen betrachten Bestellungen bis zu zwölf Monate zurück, Erstattungen ein kürzeres Fenster. Das steht an jedem Fakt.
• Was nicht gemessen wird, wird gesagt: Kundenservice, Produktqualität und Meinungen bleiben außen vor, und das Feld not_measured sagt es.
• Keine Daten, keine Aussage: Hat ein Shop nicht genügend Daten, antwortet der Fakt not_measured mit seinem Grund, nicht mit „nein“.

Grenzen und Fehler

• Bis zu 120 Anfragen pro Minute von derselben Adresse. Darüber hinaus 429.
• 404 mit tienda_no_registrada wenn dieser Shop nicht im Register steht.
• 400 mit dominio_no_valido wenn das Angefragte keine Domain ist.
• Sie lässt sich aus dem Browser aufrufen: Die API erlaubt jede Herkunft.
• Antworten dürfen fünf Minuten zwischengespeichert werden. Die Daten werden einmal täglich neu berechnet.

Was die API nicht tut

Es gibt keine Shop-Liste und keine Möglichkeit, ihre Anzahl zu erfahren: Abgefragt wird einer nach dem anderen, über die Domain. Das ist Absicht, um die Geschäftsdaten der registrierten Shops zu schützen.

Schreiben ist ebenfalls nicht möglich: Niemand kann eine Akte von außen ändern, auch nicht gegen Bezahlung. Die Fakten stammen aus dem, was Versand- und Zahlungsdienstleister erfassen.

Nutzungsbedingungen

Sie dürfen diese Daten nutzen und zitieren, unter Angabe der Quelle holdmark.org und mit Link auf die Akte des Shops. Was Sie nicht dürfen, ist sie als etwas anderes darzustellen, als sie sind: Es sind über einen Zeitraum gemessene Fakten, keine Empfehlung und keine Garantie für einen konkreten Kauf.

Wenn Sie damit etwas bauen und mehr Volumen brauchen, als das Limit zulässt, schreiben Sie an equipo@holdmark.org.