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

Die Liste des Registers

Alle Shops im Register, mit einer Übersicht ihrer Zahlen und dem Link zur vollständigen Akte:

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

Sie lässt sich filtern und sortieren. Zum Beispiel die, die die veröffentlichten Grenzwerte einhalten, nach Lieferquote absteigend:

curl "https://holdmark.org/api/v1/tiendas?meets_limits=true&sort=delivers_orders&order=desc"

• category: die Kategorie, die der Händler angibt.
• meets_limits: ob der Shop die veröffentlichten Grenzwerte einhält.
• sort: nach Domain, nach Zeit im Register oder nach einer der Zahlen.
• order: aufsteigend oder absteigend.
• limit und offset: wie viele und ab welcher, bis zu hundert pro Anfrage.

holdmark bewertet Shops nicht in einer Rangfolge. Es veröffentlicht von allen dieselben Fakten, nach derselben Regel berechnet, und sortiert wird von dem, der fragt. Es gibt keine Note und keinen Platz, und die Standardsortierung ist mit Absicht alphabetisch: Eine Standardsortierung nach Qualität wäre bereits unsere Meinung. Und sobald der Platz Umsatz bewegte, würde die Zahl aufhören zu messen und zu einem Ziel werden, das man verfolgt, indem man die schwierigen Bestellungen storniert.

Die Kategorie gibt der Händler an, und wir prüfen sie nicht: zu entscheiden, womit ein Shop handelt, ist ein Urteil, und das Register fällt keine Urteile. Deshalb ist sie bei jedem Shop als angegeben gekennzeichnet, nie als geprüft.

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 not_in_registry wenn dieser Shop nicht im Register steht. Nicht drin zu sein ist kein Urteil über ihn: Das Register enthält nur Shops, die ihre Daten verbunden haben.
• 400 mit invalid_domain wenn das Angefragte keine Domain ist.
• 400 mit invalid_parameter wenn ein Filter oder eine Sortierung der Liste nicht gültig ist. Die Antwort sagt welcher und was zulässig 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 erstellt keine Rangfolge, vergibt keine Noten und empfiehlt keinen Shop. Es liefert Fakten mit Quelle und Zeitraum, und wer fragt, entscheidet, was ihm wichtig ist. Es veröffentlicht auch nicht, wie viele Bestellungen ein Shop hat: Das Volumen geht in Stufen, nie als genaue Zahl.

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.