For programs and assistants

The registry API

Format holdmark-expediente/1.0 · version v1

Everything holdmark publishes about a store can be read from a program: no keys, no sign-up, free. It is the same information anyone sees on that store's page, in a format meant for a machine to understand.

How to use it

One request, one store, by its domain:

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

The domain may be given with www. or without it, in upper or lower case: the answer is the same. To find out what is available and what everything is called, the API describes itself:

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

What it returns

The store's full record. Every fact carries its answer, its source and the period it covers:

{
  "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"
}

How to read the figures

• Rounding always against the store: the favourable rounded down and the unfavourable rounded up. A store never comes out better than it is.
• Volume in bands: never the exact order count, only the band ("50,000+").
• Every figure with its period: bank disputes look at orders up to twelve months old; refunds use a shorter window. It is stated on each fact.
• What is not measured is stated: customer service, product quality and opinions are out of scope, and the field not_measured says so.
• No data, no claim: if a store does not have enough data, the fact answers not_measured with its reason, not "no".

Limits and errors

• Up to 120 requests per minute from the same address. Beyond that limit, 429.
• 404 with tienda_no_registrada if that store is not in the registry.
• 400 with dominio_no_valido if what is requested is not a domain.
• It can be called from the browser: the API allows any origin.
• Responses may be cached for five minutes. The data is recalculated once a day.

What the API does not do

There is no store listing and no way to find out how many there are: you query them one at a time, by domain. That is deliberate, to protect the commercial information of the registered stores.

Nor is there any writing: nobody can change a record from outside, not even by paying. The facts come from what the carrier and the payment processor record.

Terms of use

You may use and quote this data, citing holdmark.org as the source and linking to the store's record. What you may not do is present it as something it is not: these are facts measured over a period, not a recommendation or a guarantee about any particular purchase.

If you build something with this and need more volume than the limit allows, write to us at equipo@holdmark.org.