Filtering
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 type | Explanation | Example |
|---|---|---|
| __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.
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 name | Type | Description |
|---|---|---|
| address | string | Postal street address |
| address_s | string | |
| area | ||
| 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_keywords | string | |
| company_name | string | Company name |
| company_name_l | string | Company name array, split by whitespace. Efficient for __startswith searches. |
| contacts__phone | string | Phone numbers of contacts |
| contacts__uid | string | Unique identifier for the contact |
| 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 |
| facts_numeric | ||
| financial_statement_keywords | string | Written content of financial statements |
| form_of_company | string | Form of company |
| industry_codes | ||
| leads | ||
| leads.content | ||
| 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 | ||
| 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__types | string | |
| prospect_addresses__industry_codes | string | Industry code of company locations |
| prospect_addresses__office_number | string | Office number of the address. Available on the countries where office number system is in use. |
| prospectexport_target | ||
| region | string | Region of the postal address |
| registration_date | datetime | Main registrations date for the company |
| related_links | string | |
| related_links__link | string | |
| sociality | float | Vainu index for social media usage (from 0 to 1) |
| staff_number | integer | Staff number |
| 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_address_s | string | |
| 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 |
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&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 6 months ago