Caching and max_age

Results are cached in our database. Every result says whether it came from cache and how old it is, and max_age lets you decide.

Every result is stored in our database. When a fresh enough copy exists, you get it straight away, and a company or domain lookup costs less. A "no such company" answered from the cache is free.

Defaults#

Without max_age, a lookup takes our copy when it is at most this old, and fetches fresh otherwise:

Check before you buy#

POST /v1/cache is free. Send it the body of a company or domain lookup and it tells you how old our copy is, whether the lookup would be answered from the cache, and what it would cost, from the cache and fetched fresh. Then choose your max_age.

Choosing freshness with max_age#

max_age is the oldest answer you accept, in seconds.

• Leave it out to use the defaults above.
• max_age: 3600 accepts answers up to an hour old and fetches anything older.
• max_age: 31536000 accepts anything up to a year old. There's no upper limit: we serve any copy we still hold, at the cache price.
• max_age: 0 always fetches fresh.

Company profiles are kept for good. Search results are kept for 30 days, and a person's profile for 30 days after its last lookup, so older ones are fetched fresh whatever max_age says.

What each response tells you#

meta.cache on every result, and the matching headers:

meta.cache.age_seconds (and the Age header) is how long ago we fetched the data, meta.cache.fetched_at is when, and meta.cache.max_age_seconds is the window that applied.

One company, one cache entry#

Every form of a company (URL variants, letter case, old slugs, the numeric id, the URN) reaches the same entry. Look up stripe and then 2135371, and the second call is a hit. A domain you looked up leads to its company's entry too: after stripe.com, POST /v1/company for stripe is a hit.

Knowing when data changed#

meta.content_hash is a hash of data. If it's unchanged since your last copy, so is the data, and you can skip your own processing.