Pagination with cursors in company data APIs
Answer in brief
Cursor pagination returns a page of results with an opaque token for the next page. Pass the token back unchanged with the same query until it is null. Cursors expire, so when the API rejects one, start again from the first page. Page-number APIs instead cap how deep you can go, so read the limit before you build a full export on them.
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
How the cursor works
GET /v1/search
The free CompanyRegistryAPI.com API returns at most limit results (1 to 25,
default 10) and a next_cursor. Its OpenAPI document says to pass that value
as cursor for the next page, and that it is null on the last page:
base=https://api.companyregistryapi.com
curl "$base/v1/search?q=nord&address_country=FI&limit=25"
# then, with the next_cursor value of that response:
curl "$base/v1/search?q=nord&address_country=FI&limit=25&cursor=$cursor"
Keep the query and filters the same on every page; only the cursor changes.
A paging loop with restart
The docs say cursors expire and that on 400 you restart from the first
page. This generator does that once, then gives up:
const base = "https://api.companyregistryapi.com";
async function* searchAll(q, filters = {}, maxPages = 20) {
let cursor = null;
let restarted = false;
for (let pages = 0; pages < maxPages; pages++) {
const params = new URLSearchParams({ q, limit: "25", ...filters });
if (cursor) params.set("cursor", cursor);
const response = await fetch(`${base}/v1/search?${params}`);
if (response.status === 400 && cursor && !restarted) {
cursor = null; // the cursor expired: start again from page one
restarted = true;
continue;
}
if (!response.ok) throw new Error(`search failed: ${response.status}`);
const page = await response.json();
yield* page.data;
cursor = page.next_cursor;
if (!cursor) return;
}
}
A restart can return companies you have already seen, so collect results by
id, not in a list:
const seen = new Map();
for await (const company of searchAll("nord", { address_country: "FI" })) {
seen.set(company.id, company);
}
maxPages is a guard: a loop that pages without end spends the rate limit on
results nobody reads.
Cursors and rate limits together
Each page is one request against the limit. At 25 results a page and 60 requests a minute, one minute of paging reads at most 1,500 results, with no room left for anything else. Combine the loop with the 429 handling wrapper, and stop early when you have found the company you need.
Page numbers and offsets
Other APIs page by number. Their documentation states the limits:
- The GLEIF API paginates search results with
page[number]andpage[size], and includes links to the first, next and last pages. - The Brønnøysund Register Centre’s open data API pages with
pageandsize, but(page+1)*sizecannot exceed 10,000; beyond that it answers400, and its documentation points to its download services for retrieving all entities.
Page numbers let you jump to a page; cursors do not. Cursors are steadier when records change between requests, because the provider keeps the position for you.
When paging is the wrong tool
If you need every company in a country, look for a bulk file or download service, not a search loop. Registers such as Brønnøysund document download services updated once a day, plus an update service for changes. Search endpoints are built for finding candidates.
Questions and answers
Can I decode or build a cursor myself?
No. Treat it as opaque, because its format can change without notice. Store it only for as long as you are paging, and pass it back exactly as received.
Should I page through every search result?
Rarely. Company search is for finding candidates; if your code pages through thousands of results, it usually needs a narrower query, a filter or a bulk data source.
Why did my cursor stop working after a few minutes?
Cursors expire. CompanyRegistryAPI.com documents that cursors expire and that on a 400 you restart from the first page, so write the restart into the loop.
Sources for this entry
- CompanyRegistryAPI.com API docs
- CompanyRegistryAPI.com OpenAPI document
- Documentation for Open Data from the Central Coordinating Register for Legal Entities
- GLEIF API documentation
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
- The first three requests (Guide)
- Cursor (Definition)
- Handling 429 and Retry-After (Guide)
- Prefix, fuzzy and description search (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. “Pagination with cursors in company data APIs.” Content reviewed . https://bestcompanydataapi.com/cursor-pagination