Caching company data API responses
Answer in brief
Cache company reads by permanent ID, keep the API's observation date with each cached record, and choose a lifetime per field rather than one for the whole response. Cache search results only briefly, because they are candidates rather than facts. Caching is also what fair use clauses ask for, and it keeps a free API's rate limit for the requests that need it.
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
Why cache at all
CompanyRegistryAPI.com’s free API terms ask you to cache what you can. A cache also lets one rate limit serve more users, and it keeps a page working when the upstream data service is briefly unavailable.
What to cache, and for how long
| Response | Cache key | Suggested lifetime | Why |
|---|---|---|---|
| Company read | id |
Hours to days, by field use | Registry facts change slowly, but status matters |
| Officers | company_id |
Hours | Personal data; show as current only when fresh |
| Search results | Query and filters | Minutes | Candidates for a person to choose from |
| Errors | Do not cache | A 503 now says nothing about later |
These lifetimes are starting points for you to tune, not the provider’s
figures. The docs promise no update frequency; a company’s as_of_date says
when its register was last observed, where known.
Key by permanent ID
Cache company records under the API’s permanent ID, never under a name or a registry number:
import time
import requests
BASE = "https://api.companyregistryapi.com"
TTL_SECONDS = 24 * 3600
_cache = {}
def company(company_id):
hit = _cache.get(company_id)
if hit and time.time() - hit["fetched_at"] < TTL_SECONDS:
return hit["record"]
response = requests.get(f"{BASE}/v1/companies/{company_id}", timeout=10)
response.raise_for_status()
record = response.json()["data"]
_cache[company_id] = {"record": record, "fetched_at": time.time()}
return record
In production, use your shared cache or database instead of a dictionary, and store the two dates separately:
fetched_at: when your system called the API.as_of_date: when the source register was last observed, from the record.
Show as_of_date to users; use fetched_at to decide when to refresh.
Check lifecycle before you overwrite
A cached ID can lead to a record that has since changed. Before you update a
stored row from a fresh read, check lifecycle.status:
fresh = company(stored_id)
status = fresh["lifecycle"]["status"]
if status == "redirected":
stored_id = fresh["lifecycle"]["canonical_id"] # read and store that one
elif status == "split":
candidates = fresh["lifecycle"]["successor_ids"] # choose among them
elif status in ("tombstoned", "restricted"):
pass # keep your row, mark it, and stop showing stale facts as current
The status and lifecycle guide explains each state.
Serve stale on upstream errors
When the API answers 503 upstream_unavailable, a cached record is often
better than an error page, as long as you label it with its dates:
def company_or_stale(company_id):
try:
return company(company_id), False
except requests.HTTPError as error:
if error.response is None or error.response.status_code != 503:
raise # a 404 or another lasting answer is not an outage
hit = _cache.get(company_id)
if hit:
return hit["record"], True # show "as of <as_of_date>, not refreshed"
raise
Fall back only on that outage. A 404 says that no company is visible under
the ID any more: serving the cached record then would show data the API has
stopped returning.
What not to do
- Do not build a mirror of the whole dataset from a lookup API. The product’s terms forbid copying a substantial part of the data to build a competing service, and the API offers no bulk download or export.
- Do not cache empty results as negative facts.
- Do not strip the attribution when you serve from cache.
Questions and answers
How long should I cache a company record?
Choose by what the fact is used for. A name shown in a list can live for days; a status used to approve a payment should be re-read close to the decision. The record's own observation date tells you how old the register fact already was.
Should I cache empty search results?
Briefly at most. An empty result only means no connected register held a match for that prefix, and coverage can change, so never treat a cached empty result as proof that a company does not exist.
Can I cache officers?
You can, but officers are personal data from public records. Keep them only as long as your product needs them, with their source, and refresh them before showing them as current.
Sources for this entry
- About CompanyRegistryAPI.com
- CompanyRegistryAPI.com API docs
- CompanyRegistryAPI.com Company Data API
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
- Store permanent IDs (Guide)
- Provenance and observation times (Guide)
- Status and lifecycle (Guide)
- Free tiers and rate limits (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. “Caching company data API responses.” Content reviewed . https://bestcompanydataapi.com/caching-company-data