Company location

The Company location (company_location) filter enables you to narrow your search results to specific geographical areas, all the way down to the city level.

📘

Note

This filter supports searching for both main and secondary locations of a company.

📖

Main vs. secondary locations

• Main location

A company's main location refers to its headquarters or primary place of business. It is typically the central hub where the company's core operations are managed, and key decisions are made.

• Secondary locations

Secondary locations include all other places where the company maintains a business presence, such as regional offices, branch locations, factories, or stores. These locations reflect the geographic extent of a company's operations beyond its main location.

Location API

To ensure alignment with the filter's expected data structure, we recommend using the Company location filter with the Veridion Location API.

The Location API returns a hierarchical list of geographical locations, making it a suitable choice for seamless integration with the filter.

📘

Note

If your use-case requires you to pass only the country information, you don't need to use the Location API.

Instead, you can pass the country as ISO 3166-1 two-digit code format (e.g. "US").

Search modes

Exact match

Use this mode if you are interested in one specific location. The filter will return results where the input location exactly matches the location recorded for the company.

To perform an exact match search, use equals in the relation parameter.

📘

Note

The country is always required, while the region and city are optional.

You can add more granularity by also including the region and city.

For instance, if you specify United States, the search will only return companies located anywhere within the United States. If you add more details, such as California and San Francisco, the search will be refined to companies specifically located in San Francisco, California, United States.

The following example shows how to search for all the companies located in San Francisco, California, United States:

{
  "attribute": "company_location",
  "relation": "equals",
  "value": {
      "country": "United States",
      "region": "California",
      "city": "San Francisco"
    }
}

Multiple exact match

This mode is convenient when you have several locations of interest at once. You can provide an array of locations, and the filter will return companies that match exactly with any of the locations in your array.

To perform a multiple exact match search, use in in the relation parameter and pass an array of locations in the value parameter.

The following example shows how to search for all the companies located in San Francisco, California, United States or in Canada:

{
  "attribute": "company_location",
  "relation": "in",
  "value": [
    {
      "country": "United States",
      "region": "California",
      "city": "San Francisco"
    },
    {
      "country": "Canada"
    }
  ]
}

📘

Note

The country field also supports ISO 3166-1 two-digit code format (e.g. "US").

For example, the following filter searches for companies located in the United States or Canada:

{  
  "attribute": "company_location",  
  "relation": "in",  
  "value": [  
    {  
      "country": "US"
    },  
    {  
      "country": "CA"  
    }  
  ]  
}

Exclude locations

To exclude locations from your results, use the corresponding not_equals and not_in values in the relation parameter.

For example, the filter below will specifically search for companies outside ("relation": "not_in") the United States and Canada:

{  
  "attribute": "company_location",  
  "relation": "not_in",  
  "value": [  
    {  
      "country": "US" 
    },  
    {  
      "country": "CA"
    }  
  ]  
}

Strictness level

📘

Note

By default, the Company location filter searches only the company's main location ( default strictness: 1 )

You can extend your search to include a company's secondary locations by providing a strictness parameter:

• strictness: 1 - searches only within the main location of the company.
• strictness: 2 - searches only within the secondary locations of the company.
• strictness: 3 - includes both the main location and secondary locations of the company.

For example, the following filter returns all companies that list their secondary location as San Francisco, California, United States:

{
  "attribute": "company_location",
  "relation": "in",
  "value": [
    {
      "country": "United States",
      "region": "California",
      "city": "San Francisco"
    }
  ],
  "strictness": 2
}

Alternatively, this filter returns all companies that only have locations (either main or secondary) outside of the U.S.:

{
  "attribute": "company_location",
  "relation": "not_in",
  "value": [
    {
      "country": "US"
    }
  ],
  "strictness": 3
}

📖

Reference

To view all available filter relations and accepted types, please check the Filter Relations section.