Limits and pagination

Limits

By default, Vainu will only respond with 20 results matching your filtering parameters, even though there would be more matches to your query. You can increase this by setting the limit parameter. The limit can be a maximum of 1000 for a single request.

Pagination

You can get more results by using an offset parameter for pagination. You can effectively go through the results in batches of 1000 by using the limit and the offset.

The offset parameter skips the number of results specified and returns the results after that. In practice, the first request would have a limit of 1000 and an offset of 0. The next one would have a limit of 1000 and an offset of 1000. By increasing the offset for subsequent requests you can paginate through all the results.

Count

You can request a total number of results with the count parameter. Using count is efficient for getting the total amount of companies without pagination, but may cause the endpoint to answer 1.5-2 times slower than usual.

Count parameters can have the value of true or include. With the value "true" only the amount of companies will be returned. With the value 'include' the count will be added to response with other data requested.

Order (sorting)

Sorting is specified with the "order" parameter. Sorting is possible with all the fields that are supported for filtering. Ascending order can be specified with a leading minus (-) character.

Fast sorting (ascending or descending) is supported with the following fields:

📘

Field supporting fast sorting

business_id, company_name, visiting_postal, visiting_city, vainu_score, turn_over, alexa_rank_global

Examples

Examples of using limit, pagination, count, and ordering.

# Return maximum of one result
https://api.vainu.io/api/v2/companies/?country=FI&city=Helsinki&limit=1

# Return maximum of 100 results
https://api.vainu.io/api/v2/companies/?country=FI&city=Helsinki&limit=1000

# Return first 100 results
https://api.vainu.io/api/v2/companies/?country=FI&city=Helsinki&offset=0&limit=100

# Skip first 100 results and return next 100
https://api.vainu.io/api/v2/companies/?country=FI&city=Helsinki&offset=100&limit=100

# Return only count
https://api.vainu.io/api/v2/companies/?country=FI&city=Helsinki&count=true

# Return count in addition of results
https://api.vainu.io/api/v2/companies/?country=FI&city=Helsinki&count=include

# Return 5 companies with highest revenue in Helsinki
https://api.vainu.io/api/v2/companies/?country=FI&city=Helsinki&limit=5&order=-turn_over

# Return first 5 companies in Helsinki in alphabetical order
https://api.vainu.io/api/v2/companies/?country=FI&city=Helsinki&limit=5&order=company_name