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

The registry listing

Every store in the registry, with a summary of its figures and a link to each full record:

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

It can be filtered and ordered. For example, the ones that meet the published limits, from best to worst delivery:

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

• category: the category the merchant declares.
• meets_limits: whether the store meets the published limits.
• sort: by domain, by time in the registry, or by any of the figures.
• order: ascending or descending.
• limit and offset: how many and from which one, up to a hundred per request.

holdmark does not rank stores. It publishes the same facts for all of them, computed with the same rule, and whoever asks does the ordering. There is no score and no position, and the default order is alphabetical on purpose: a default order by quality would already be an opinion of ours. And as soon as position moved sales, the figure would stop measuring and become a target you chase by cancelling the difficult orders.

The category is declared by the merchant and we do not check it: deciding what a store sells is a judgement, and the registry makes no judgements. That is why every store carries it marked as declared, never as checked.

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 not_in_registry if that store is not in the registry. Not being there is not a judgement about it: the registry only holds stores that connected their data.
• 400 with invalid_domain if what is requested is not a domain.
• 400 with invalid_parameter if a filter or order in the listing is not valid. The answer says which one and what is accepted.
• 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

It does not rank stores, does not score them and recommends none. It returns facts with their source and their period, and whoever asks decides what matters to them. It also does not publish how many orders each store has: volume goes in bands, never the exact figure.

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.