POST
/
markets
/
discover
curl --request POST \
  --url https://api.forestreet.com/markets/discover \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "type": "<string>",
  "marketId": "<string>",
  "marketName": "<string>",
  "marketRole": "<string>",
  "searchTerms": [
    "<string>"
  ],
  "domains": [
    "<string>"
  ],
  "country": "<string>",
  "countries": [
    "<string>"
  ]
}'
{
  "marketId": 2
}

​
Body Request Object Example

{
    "type": "keyword",
    "marketId": null,
    "marketName": "Transcription Services",
    "searchTerms": ["AI Transcription"],
    "domains": ["ai-media.tv", "rev.com"],
    "countries": ["all", "US", "GB"]
}

​
Body

​
type
string
default:"keyword"

This is the type of search you would like to run. Default is keyword, more options coming soon.

​
marketId
string
default:"null"

If you want to find more companies in an existing market, you can provide the marketId here. New companies will be added to this market.

If you want to start a new market, you can leave this field empty or set it to null.

Access Permissions: If you do not have permission to access the market, or the market does not exists, a 403 FORBIDDEN will be emitted instead.

To prevent predictable serial number attacks, this end point does not distinguish between a market that does not exist and a market that you do not have access to.
Divergent markets within the same study: It is up to the caller to ensure that the market definition remains consistent between discoveries. You are permitted to search a completely different market with the same marketId, but this is strongly advised against since the market analysis may not be able to understand divergent market properties, and produce misappropriated features and insights.
​
marketName
string
required

This is the name of the market you would like to search for.

​
marketRole
string

Try to limit the companies to ones that fit a specific role in the market. Possible values are:

  • "manufacturer" - physical product manufacturing, e.g. a car manufacturer
  • "distributor" - physical product distribution, e.g. a car dealership
  • "service provider" - contractor or provider of pre-defined services, e.g. a car repair shop
  • "consultant" - consultants or advisers not themselves participating in the market, but offers advice to those who do, e.g. a motor regulatory consultant

This is a hint to the discovery process and does not guarantee that all returned companies will fit this role. If insufficient companies are found, the search will be broadened to include other roles.

If not provided, the AI will attempt to infer the role based on the market name, and assumes "manufacturer" if the market is too broad.

It is recommended to write your intended role in the market name, which the AI will be able to infer from. Supplying a marketRole incompatible with the market name might degrade the output.
​
searchTerms
array<string>
default:"[]"

This is an array of search terms to use for the search. If no search terms are provided, we automatically generate a list of search terms related to the market name.

​
domains
array<string>
default:"[]"

This is an array of domains to use for the search. If no domains are provided, we automatically generate a list of domains related to the market name.

This is typically not required. The discovery process heavily relies on the market and the keywords; the domains are only used to infer the scope of the market. They are guaranteed to be included in the results.

​
country
string
default:"all"
deprecated

This is the country you would like to search in.

Only one of country or countries should be provided; otherwise a 400 BAD REQUEST will be returned with an error message.
This parameter is deprecated and is supported for backward compatibility only. Please use countries instead.
​
countries
array<string>
default:"['all']"

This is an array of countries you would like to search in. You can supply up to 5 ISO-3166-1 alpha-2 country codes, including up to one instance of all, which represents a global search in addition to other specified countries.

Currently, candidates from all countries are pooled together for evaluation; it does not guarantee that some candidates will be returned from each specified country. This search assumes the user is interested in candidates from any of the specified countries.

Defaults to ['all'].

Only one of country or countries should be provided; otherwise a 400 BAD REQUEST will be returned with an error message.

​
Response

​
marketId
number

A unique identifier for the market, used to retrieve the progress and results.

{
  "marketId": 2
}