Using filtering parameters

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.

Acceptable HTTP Methods GET/POST

Example of requesting data of two domains for companies in Finland.

Using GET Method

GET https://api.vainu.io/api/v2/companies/?country=FI&limit=2&domain__in=fingrid.fi,nokia.com&fields=domain,website_traffic_data.ranking

Using POST Method

Same query using Post method. Post method is useful when you need to add more filters that fit to GET request URL. You get data for list of 50000 domains.

POST https://api.vainu.io/api/v2/companies/

Payload: 
{  
    "country": "FI",  
    "limit": 2,  
    "domain\_\_in": ["fingrid.fi","nokia.com"],  
    "fields": ["domain","website_traffic_data.ranking"]  
 }

Filter types

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:

Filter typeExplanationExample
__gteValue has to be greater or equalstaff_number__gte
__gtValue has to be greaterstaff_number__gt
__lteValue has to be less or equalturn_over__lte
__ltValue has to be lessturn_over__lt
__startswithString starts with the valuecompany_name__startswith
__containsString includes this value (case sensitive)company_name__contains
__icontainsString includes this value (case insensitive)company_name__icontains
__neValue 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.

Combination of multiple parameters

Multiple filtering parameters can be used to build more complex queries. If the same parameter is used multiple times they are processed as an OR query. If different parameters are used multiple times they are processed as an AND query. Both same and different parameters can be used in the same query.

Format of the business ID

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.

Multiple 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.

https://api.vainu.io/api/v2/companies/?business_id=DK39248530,DK40494197

Using queries built inside the Vainu platform

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.

https://api.vainu.io/api/v2/companies/?list=5ca6d481f447382da73a8ef4

Inactive companies

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.

Matching

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

Geolocation and coordinates

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.

πŸ“˜

Calculating radians

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

Supported fields for filtering

Parameter nameTypeDescription
addressstringPostal street address
address_sstring
area
alexa_rank_globalintegerGlobal alexa rank
basic_modifieddatetimeTimestamp when basic data has been updated
business_idstringBusiness id / organisation number of the company
citystringCity of postal address
company_keywordsstring
company_namestringCompany name
company_name_lstringCompany name array, split by whitespace. Efficient for __startswith searches.
contacts__phonestringPhone numbers of contacts
contacts__uidstringUnique identifier for the contact
countrystringCountry of the company
development_of_turnoverfloatTurnover change in percentage
digitalityfloatVainu index describing digital adoption in the company (from 0 to 1)
domainstringCompany main domain
employer_register_datedatetimeDatetime when company has been registered to employer register
facebook_linkstringLink to the facebook profile
facts_numeric
financial_statement_keywordsstringWritten content of financial statements
form_of_companystringForm of company
industry_codes
leads
leads.content
linkstringLink to main website of company
linkedin_idstringLinkedIn Id of the company
marketilityfloatVainu index describing marketing tech used by company (from 0 to 1)
motherstringBusiness id of the mother company in the group
mother_foreignstringBusiness id of the mother company of the group, if the company is from another country
municipalitystringMunicipality of the postal address
modificationsdatetimeTimestamp when the company data has been updated
nstatusstringNormalised status of the company (inactive or active)
phonestringMain phone number of the company
postalstringPostal number of the postal address
profitfloatProfit of the company in percentage
prospect_addresses
prospect_addresses__addressstringStreet addresses of company locations
prospect_addresses__citystringCities of company locations
prospect_addresses__municipalitystringMunicipalities of company locations
prospect_addresses__office_namestringOffice names of company locations
prospect_addresses__postalstringPostal numbers of company locations
prospect_addresses__regionstringRegions of company locations
prospect_addresses__typesstring
prospect_addresses__industry_codesstringIndustry code of company locations
prospect_addresses__office_numberstringOffice number of the address. Available on the countries where office number system is in use.
prospectexport_target
regionstringRegion of the postal address
registration_datedatetimeMain registrations date for the company
related_linksstring
related_links__linkstring
socialityfloatVainu index for social media usage (from 0 to 1)
staff_numberintegerStaff number
staff_number_growthfloatPercentage of change of staff number
statusstringOfficial status of the company
turn_overfloatRevenue of the company (EUR)
turn_over_localfloatRevenue in local currency
twitter_linkstringLink to twitter profile of the company
urls_keywordsstringKeywords collected from company website
urls_web_tags__namestringTechnologies collected from company website
urlsstringOther URL's belonging to company
vidstringVainu ID for the company
vainu_custom_industrystringVainu custom industry name
visiting_addressstringVisiting street address
visiting_address_sstring
visiting_citystringCity of visiting address
visiting_municipalitystringMunicipality of visiting address
visiting_postalstringPostal number of the visiting address
visiting_regionstringRegion of the visiting address

Filtering examples

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&ampregion__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