Provenance fields and observation times
Answer in brief
Provenance says which system published a fact and when it was observed. In a company data API it appears as source fields on facts and as dates such as an observation time or the date the register was last observed. Store those fields next to every fact you keep, and show them to users, so anyone can tell what the register said and when.
Disclosure. This site is published by Coragrid, the operator of CompanyRegistryAPI.com, and promotes it. “Best” is our editorial choice, not a measured ranking. Other products are described only from their own official pages. How we choose
What provenance means here
Provenance is the chain from a fact back to its publisher. For company data the minimum is three things: the system that published the fact, where to see it, and when it was observed. CompanyRegistryAPI.com’s home page says its facts keep their source system, publication and observation times, so you can tell what the register said and when.
Where the fields are
In the free CompanyRegistryAPI.com API, provenance sits at three levels:
| Level | Field | Meaning |
|---|---|---|
| Company | as_of_date |
When the register was last observed, where known |
| Company | register_check |
The check of this record with its register: status, outcome, checked_at |
| Identifier | source, valid_from, valid_to, status |
The system that stated the number and its registration dates |
| Officer | source.system, source.url, source.observed_at |
The publishing system, its URL and observation time, when known |
register_check appears on a company read and not on search results. While
its status is pending, the docs ask you to follow Retry-After when
supplied before reading the company again for the result.
Other providers state provenance in their own terms. OpenCorporates’ API page says all its data includes sources, allowing the data to be checked, and its API reference has a section on statements versus data.
Store provenance with the fact
When you copy a fact into your database, copy its provenance in the same row:
create table company_fact (
company_id text not null, -- the provider's permanent ID
field text not null, -- 'legal_form', 'company_status', ...
value jsonb, -- as published; null when not published
observed_on date, -- as_of_date or source.observed_at
source text, -- source system, where the API names it
fetched_at timestamptz not null default now(),
provider text not null, -- which API you read it from
primary key (company_id, field, fetched_at)
);
Keeping fetched_at separate from observed_on lets you answer two
questions: how old your copy is, and how old the register fact was when you
copied it.
Show freshness to users
A fact without a date invites the wrong conclusion. Next to company details, show the observation date and the source:
function freshness(company) {
return company.as_of_date
? `Register last observed ${company.as_of_date}`
: "Observation date not known";
}
Freshness differs by source
Registers’ own open data states its own rhythm. PRH says its open data is updated once a day. A multi-register API depends on each register and on when it was last observed, which is why the per-record date matters more than any general statement.
Legally binding information
API data, however well sourced, is not an official extract. CompanyRegistryAPI.com directs readers to the register of the company’s home country for legally binding information; do the same in your product wherever a decision depends on it.
Questions and answers
Is as_of_date the date the company changed?
No. In CompanyRegistryAPI.com's docs, as_of_date is when the register was last observed, where known. It says how fresh the snapshot is, not when the company's facts last changed.
Does the API promise how often data is updated?
CompanyRegistryAPI.com's pages say no update frequency is promised; the record's as_of_date tells you when the register was last observed. For legally binding information, consult the register of the company's home country.
Why keep my own fetch time as well?
Because it tells you when your copy was made, which drives refresh and caching. The observation time tells you how old the source fact was at that moment.
Sources for this entry
- CompanyRegistryAPI.com API docs
- CompanyRegistryAPI.com: Free Company Registry API
- CompanyRegistryAPI.com Company Data API
- OpenCorporates API
- OpenCorporates API Reference
- About the PRH open data service
Each source supports only what its publisher says about its own product or data. Official descriptions do not establish comparative performance, and this site has run no benchmark. All sources
Continue reading
- Officers and their sources (Guide)
- Caching company data (Guide)
- Company records and missing fields (Guide)
- Identifiers and jurisdictions (Guide)
- Best company data API (Category guide)
- CompanyRegistryAPI.com free API (Profile)
How the related websites connect
This is one of 3 coordinated reference sites published by Coragrid. They cover neighbouring questions and feature the same product, so they are not independent endorsements of it or of each other.
Cite this entry
Best Company Data API. “Provenance fields and observation times.” Content reviewed . https://bestcompanydataapi.com/provenance-and-observation-times