The most common starting point with Vainu API is to find the correct company or companies with the data or data ranges you have in mind.
With the filtering parameters, you can build complex searches or simple targeting queries to get correct results. Filtering parameters are available for either when searching for companies or signals from our databases. The most simple query might be defining a business ID to find the correct entity, while more complex queries might include combinations of financial, technographic, or location parameters.
Each filtering parameter can be used as they are to get all results where this value is exactly as requested. Sometimes this isn't enough and parameters can be combined with specific suffixes to get more flexible results or to do a certain type of operation.
Each filter type is added to the end of the parameter name.
Supported filter types are:
|__gte||Value has to be greater or equal||staff_number__gte|
|__gt||Value has to be greater||staff_number__gt|
|__lte||Value has to be less or equal||turn_over__lte|
|__lt||Value has to be less||turn_over__lt|
|__startswith||String starts with the value||company_name__startswith|
|__contains||String includes this value (case sensitive)||company_name__contains|
|__icontains||String includes this value (case insensitive)||company_name__icontains|
|__ne||Value is not equal to his. Use "null" to filter out non existing values.||phone__ne|
Case insensitive parameters
Parameters: company_name, visiting_city, city, visiting_municipality, municipality are case insensitive by default.
Multiple filtering parameters can be used to build more complex queries. If the same parameter is used multiple times they are processed as an AND query. If different parameters are used multiple times they are processed as an OR query. Both same and different parameters can be used in the same query.
The behavior of the business_id parameter differs slightly depending on whether or not the country parameter is used.
If one country is given, the business_id does not have to be in exactly the same format as in the Vainu database. Querying with ?country=NL&business_id=2123341 would find a company with business_id of NL2123341.
If none or more than one country is given, the business ID should be in the same format as in the Vainu database, or it should be in a format that is unique to a country. A business id that is unique to a country should have the country code as a prefix (FI2123341, NL2123341) or have a format such as 0123456-7 which is unique to Finnish business ids.
Sometimes you have multiple business IDs and wish to get data from these. In this case, you can use the business_id parameter with multiple values when they are separated with a comma, all the values as processed as an OR.
The Vainu platform offers a search engine where multiple complex queries can be constructed in a visual interface. These lists are considered to be either dynamic or static. Dynamic lists are based on filters and content in the list changes when the data changes. Static lists are user uploaded or inserted companies where the content of the list stays the same.
Vainu API offers tools to manage these lists, which are discussed in greater detail under Lists and Customer data. For filtering purposes, these lists can be used as filtering parameters and the content created at the platform can be accessed through the API.
List parameter accepts only the list ID found either from the Lists API or from the URL at the platform.
Vainu offers two different fields to imply the status of the company. These fields are status and nstatus. Status is the official, usually country-specific status from the local official authorities. Vainu has created a normalized status (nstatus) where the value is either active or inactive.
Vainu API offers a built-in matching function. Matching is enabled by giving matching=true as a parameter. When using the matching functionality API will return a single company if an accurate match is found. When no match or accurate match can't be found with the data sent, no companies will be returned.
All the parameters support incomplete and even slightly wrong data when using matching functionality and there is no need to use types of filtering parameters. The country parameter is usually recommended to be used, as it will greatly increase matching accuracy.
Fields supporting matching
country, company_name, business_id, address, domain
Searching companies with coordinates is possible with a sphere function. This allows searches with point coordinates and a radius.
Query format for sphere is coordinates__geo_within_sphere=,, . Radius is given in radians and can be calculated with a simple function below.
Radians needed for the radius can be calculated with target radius divided by equatorial radius of the Earth (6378.1 km / 3963.2 miles). Both target radius and equatorial radius has to be in same units.
Example radius of 10km: 10 / 6378.1 = 0.001568
The behaviour of the coordinates field is a little bit different from other fields available for filtering. By default, coordinate queries target root-level coordinates that is the registered main location of the company. If any filters pointing to addressess (prospect_addresses__ ...) is present, the coordinate query targets the address list instead of the root address.
https://api.vainu.io/api/v2/companies/ ?country=FI &fields=company_name,business_id &coordinates__geo_within_sphere=23.758621215820312,61.503699951545485,0.00005
https://api.vainu.io/api/v2/companies/ ?country=FI &fields=company_name,business_id &coordinates__geo_within_sphere=23.758621215820312,61.503699951545485,0.00005 &prospect_addresses__visiting_city=Tampere &limit=1000
|address||string||Postal street address|
|alexa_rank_global||integer||Global alexa rank|
|basic_modified||datetime||Timestamp when basic data has been updated|
|business_id||string||Business id / organisation number of the company|
|city||string||City of postal address|
|company_name_l||string||Company name array, split by whitespace. Efficient for __startswith searches.|
|contacts__phone||string||Phone numbers of contacts|
|country||string||Country of the company|
|development_of_turnover||float||Turnover change in percentage|
|digitality||float||Vainu index describing digital adoption in the company (from 0 to 1)|
|domain||string||Company main domain|
|employer_register_date||datetime||Datetime when company has been registered to employer register|
|facebook_link||string||Link to the facebook profile|
|financial_statement_keywords||string||Written content of financial statements|
|form_of_company||string||Form of company|
|link||string||Link to main website of company|
|linkedin_id||string||LinkedIn Id of the company|
|marketility||float||Vainu index describing marketing tech used by company (from 0 to 1)|
|mother||string||Business id of the mother company in the group|
|mother_foreign||string||Business id of the mother company of the group, if the company is from another country|
|municipality||string||Municipality of the postal address|
|modifications||datetime||Timestamp when the company data has been updated|
|nstatus||string||Normalised status of the company (inactive or active)|
|phone||string||Main phone number of the company|
|postal||string||Postal number of the postal address|
|profit||float||Profit of the company in percentage|
|prospect_addresses__address||string||Street addresses of company locations|
|prospect_addresses__city||string||Cities of company locations|
|prospect_addresses__municipality||string||Municipalities of company locations|
|prospect_addresses__office_name||string||Office names of company locations|
|prospect_addresses__postal||string||Postal numbers of company locations|
|prospect_addresses__region||string||Regions of company locations|
|prospect_addresses__industry_codes||Industry code of company locations|
|region||string||Region of the postal address|
|registration_date||datetime||Main registrations date for the company|
|sociality||float||Vainu index for social media usage (from 0 to 1)|
|staff_number_growth||float||Percentage of change of staff number|
|status||string||Official status of the company|
|turn_over||float||Revenue of the company (EUR)|
|turn_over_local||float||Revenue in local currency|
|twitter_link||string||Link to twitter profile of the company|
|urls_keywords||string||Keywords collected from company website|
|urls_web_tags__name||string||Technologies collected from company website|
|urls||string||Other URL's belonging to company|
|vid||string||Vainu ID for the company|
|vainu_custom_industry||string||Vainu custom industry name|
|visiting_address||string||Visiting street address|
|visiting_city||string||City of visiting address|
|visiting_municipality||string||Municipality of visiting address|
|visiting_postal||string||Postal number of the visiting address|
|visiting_region||string||Region of the visiting address|
We have collected some examples of filtering parameters on the tabs below.
# Single business id with country prefix https://api.vainu.io/api/v2/companies/?business_id=NO918443525 # Single business id without country prefix https://api.vainu.io/api/v2/companies/?country=NO&business_id=918443525 # Multiple business id's https://api.vainu.io/api/v2/companies/?business_id==DK39248530,DK40494197
# Company with a name Vainu Finland Oy https://api.vainu.io/api/v2/companies/?company_name=Vainu%20Finland%20Oy&country=FI # Any word of company name begins with Vainu https://api.vainu.io/api/v2/companies/?company_name_l__startswith=vainu&country=FI
# Domain vainu.com https://api.vainu.io/api/v2/companies/?country=FI&domain=vainu.com # Domain starts with vainu https://api.vainu.io/api/v2/companies/?country=FI&domain__startswith=vainu
# Country and region https://api.vainu.io/api/v2/companies/?country=FI&region__exact=FI-18 # Postal code starts with https://api.vainu.io/api/v2/companies/?visiting_postal__startswith=905&country=FI # Postal code range https://api.vainu.io/api/v2/companies/?visiting_postal=50000-51019&limit=20&country=SE
# Vainu custom industry starts with "construction" https://api.vainu.io/api/v2/companies/?country=FI&vainu_custom_industry__startswith=construction # Companies with Finnish industry code starting with 60 https://api.vainu.io/api/v2/companies/?country=FI&industry_codes__startswith=60 # 20 companies with the biggest turn over with Finnish industry code 60201 https://api.vainu.io/api/v2/companies/?country=FI&industry_codes__startswith=60201&limit=20&order=-turn_over
# Companies with Zendesk as recongized technology https://api.vainu.io/api/v2/companies/?country=FI&urls__web_tags__name__startswith=zendesk
# URL Keywords https://api.vainu.io/api/v2/companies/?country=NL&urls_keywords__startswith=machine%20learning # Company keywords https://api.vainu.io/api/v2/companies/?country=FI&company_keywords__startswith=database # Financial statement keywords https://api.vainu.io/api/v2/companies/?country=FI&financial_statement_keywords__startswith=growth
# Staff number over 100 https://api.vainu.io/api/v2/companies/?staff_number__gt=100 # Turn over between 500000 - 600000 https://api.vainu.io/api/v2/companies/?turn_over__gte=500000&turn_over__lte=600000
Updated 3 months ago