Skip to main content
POST
Expansion Overview

Authorizations

​
pubrio-api-key
string
header
required

A unique API token that represents the actions you perform through the API and the corresponding permissions and operations. You can create it through the Settings section.

Body

application/json
​
froms
string[]

Origin markets (ISO 3166-1 alpha-2). Where a company is expanding FROM — its home / HQ countries. Use alone to find companies growing out of these markets; combine with tos for a specific from→to corridor.

Example:
​
tos
string[]

Target markets (ISO 3166-1 alpha-2). Where a company is expanding TO. Use alone to find every company entering these markets; combine with froms for a specific from→to corridor.

Example:
​
exclude_froms
string[]

Origin markets to exclude (ISO 3166-1 alpha-2).

Example:
​
exclude_tos
string[]

Target markets to exclude (ISO 3166-1 alpha-2).

Example:
​
stages
enum<string>[]

Values are case-sensitive and are not validated. An unrecognised value is silently discarded rather than rejected: on stages, freshness, scopes and momentum the whole filter is dropped and you get unfiltered results, while on signal_types and signal_strengths the filter is applied and matches nothing. Either way the response looks normal. Resolve valid slugs from Expansion Reference and compare data.pagination.total_entries against an unfiltered call if a result set looks wrong.

Available options:
exploring,
committing,
expanding,
scaling,
established
Example:
​
momentum
enum<string>[]

Trajectory of the company's movement in the market. advancing is gaining ground, steady is holding, pulling_back covers retreat and contraction.

Do not use the values from directions in Expansion Reference here. Those (advancing, steady, retreating, new) are the response values you get back on stage.direction; only the three listed above are accepted as a filter. Sending retreating or new silently disables the filter and returns unfiltered results.

Available options:
accelerating,
advancing,
steady,
pulling_back
Example:
​
freshness
enum<string>[]

Values are case-sensitive and are not validated. An unrecognised value is silently discarded rather than rejected: on stages, freshness, scopes and momentum the whole filter is dropped and you get unfiltered results, while on signal_types and signal_strengths the filter is applied and matches nothing. Either way the response looks normal. Resolve valid slugs from Expansion Reference and compare data.pagination.total_entries against an unfiltered call if a result set looks wrong.

Available options:
fresh,
cooling,
stale,
cold
Example:
​
scopes
enum<string>[]

Filter by market-entry scope.

Available options:
entering_new_market,
expanding_within_presence,
established_only
Example:
​
ahead_of_pace
boolean

Limit to company/market pairs moving faster than the typical pace for that market.

Example:

false

​
signal_types
enum<string>[]

Values are case-sensitive and are not validated. An unrecognised value is silently discarded rather than rejected: on stages, freshness, scopes and momentum the whole filter is dropped and you get unfiltered results, while on signal_types and signal_strengths the filter is applied and matches nothing. Either way the response looks normal. Resolve valid slugs from Expansion Reference and compare data.pagination.total_entries against an unfiltered call if a result set looks wrong.

Available options:
AD,
NEWS,
DNS,
INFRA,
PARTNER,
EVENT_PLUS,
EXEC,
OFFICE,
HIRE,
SCALE,
PRODUCT
Example:
​
signal_strengths
enum<string>[]

Values are case-sensitive and are not validated. An unrecognised value is silently discarded rather than rejected: on stages, freshness, scopes and momentum the whole filter is dropped and you get unfiltered results, while on signal_types and signal_strengths the filter is applied and matches nothing. Either way the response looks normal. Resolve valid slugs from Expansion Reference and compare data.pagination.total_entries against an unfiltered call if a result set looks wrong.

Available options:
low,
medium,
high
Example:
​
min_signal_count
integer

Minimum number of expansion signals a company must have in the window — "very active / heavy footprint".

Example:

3

​
only_contraction
boolean

When true, return only contraction-flagged expansions (companies scaling back).

Example:

false

​
verticals
integer[]

A list of vertical_id used to search for companies in a specific vertical or industry. To find the ID, call the vertical endpoint under the Filters tab.

This filter supports is_enable_similarity_search, once enabled you can enter any free text, e.g. ["AI"].

​
vertical_categories
integer[]

A list of vertical_category_id used to search for companies in a specific vertical category. To find the ID, call the vertical category endpoint under the Filters tab.

This filter supports is_enable_similarity_search, once enabled you can enter any free text, e.g. ["Information Technology"].

​
vertical_sub_categories
integer[]

A list of vertical_sub_category_id used to search for companies in a specific vertical sub-category. To find the ID, call the vertical sub category endpoint under the Filters tab.

This filter supports is_enable_similarity_search, once enabled you can enter any free text, e.g. ["Software"].

​
technologies
integer[]

A list of tag_id used to search for specific technologies used by companies. To find the ID, call the technology endpoint under the Filters tab.

This filter supports is_enable_similarity_search, once enabled you can enter any free text, e.g. ["Shopify"].

​
employees
string[][]

The number range of employees working for the company. This enables you to find companies based on headcount. You can add multiple ranges to expand your search results.

Check out company size endpoints under the Filters tab for more information.

Example:
​
revenues
integer[]

Minimum and maximum range of company revenue.

Example:
​
founded_dates
integer[]

Years of company founded range. The maximum value founded is the current year.

Example:
​
keywords
string[]

A list of keywords to filter companies by relevance, specialties, or descriptions.

Example:
​
companies
string[]

Scope to specific companies by any mix of domain_search_id, company domain, or a company social media profile URL. Domains and URLs resolve to their best-ranked company.

Example:
​
job_locations
string[]

ISO 3166-1 alpha-2 (cca2) is used for filtering locations. Check out location endpoints under the Filters tab for more information.

Example:
​
job_exclude_locations
string[]

Geographic locations to exclude from job posting results.

Example:
​
job_posted_dates
string[]

Date range of the posted date. The maximum value is the current day.

Example:
​
job_titles
string[]

Job titles associated with the individuals you aim to locate.

The results will also encompass job titles that include similar terminology, even if they do not match exactly. For instance, searching for software engineer may yield results for individuals with the title senior software engineer.

Example:
​
advertisement_target_locations
string[]

Target geographic locations for advertisements.

Example:
​
advertisement_exclude_target_locations
string[]

Geographic locations to exclude from advertisement targeting.

Example:
​
advertisement_search_terms
string[]

Keywords used to search within advertisement content or titles.

Example:
​
advertisement_start_dates
string<date>[]

Start date range for advertisement filtering.

Example:
​
advertisement_end_dates
string<date>[]

End date range for advertisement filtering.

Example:
​
news_categories
string[]

List of category slugs for searching for specific news categories. To find a slug, call the news categories endpoint under the Filters tab.

Example:
​
news_published_dates
string[]

Date range of the published date. The maximum value is the current day.

Example:
​
transitioned_dates
string<date>[]

ISO date range [start, end] for the display window (map, flows, and watchlist timeline). Defaults to the last 90 days. The new_transitions_30d KPI always uses its own fixed 30-day window regardless of this range.

Example:
​
window_days
integer

Optional. Size of the rolling window in days. Used when an explicit transitioned_dates range is not supplied; if both are omitted, a default window is used.

Example:

90

​
min_markets
integer

Minimum number of new markets a company must have entered in the window (wide expanders).

Example:

3

​
home_country_code
string[]

Filter by company home country (ISO 3166-1 alpha-2). Intersects with froms when both are supplied.

Example:
​
industries
string[]

Filter by industry name (free-text match).

Example:
​
exclude_industries
string[]

Industries to exclude (free-text match).

Example:
​
select_size
integer

Max markets to return (plan-capped).

Example:

250

​
flows_size
integer

Max cross-border flows to return (plan-capped).

Example:

50

​
is_include_metadata
boolean

Return the full detail payload. API-key traffic is lean by default: the model block, the confidence figures (stage.confidence on Company Expansion Detail, confidence_score on other_markets[] and on Rankings markers[]) and the established_min / share_of_detected / has_known_office fields are all omitted unless this is true.

Example:

true

Response

200 - application/json

Market dashboard aggregates.

​
metadata
object
​
data
object

Dashboard container: ranked markets plus the top corridor flows. Deprecated legacy mirror. Every container inside data is also emitted at the top level (countries, top_flows, picks_aggregate, watchlist_markets, watchlist_timeline) for older clients. Read them from data — the top-level copies will be removed.