Search Existing Markets

POST

markets

curl --request POST \
  --url https://api.forestreet.com/markets/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "keyword": "<string>",
  "company": "<string>",
  "marketId": 123,
  "hsCode": [
    {}
  ],
  "page": 123,
  "itemsPerPage": 123,
  "collectionId": 123
}'

{
    "meta": {
        "currentPage": 1,
        "itemsPerPage": 25,
        "totalItems": 13,
        "totalPages": 1,
        "collectionId": 123,
    },
    "data": {
        "_id": "6690ff4679b5056b6bedfab3",
        "marketId": 4815,
        "name": "Stainless Steel Manufacturers",
        "subtitle": "Stainless Steel Manufacturers",
        "description": "Externally created study",
        "headerImageUrl": "https://ailsa-study-thumbnails.s3.eu-west-2.amazonaws.com/default-thumbnail%402x.jpg",
        "companyCount": 30,
        "hsCodes": [
            "7202",
            "7218",
            "7221",
            "7222",
            "7223",
            "7224",
            "7225",
            "7226"
        ],
        "topMeanScore": 0.84506,
        "createdAt": "2024-07-12T09:57:27.000Z",
        "versionDate": "2024-07-12T10:02:46.976Z",
        "searchCriteria": [
            {
                "marketName": "Stainless Steel Manufacturers",
                "countries": [
                    "all"
                ],
                "keywords": [
                    "SHS",
                    "UC",
                    "Universal Beam",
                    "Structural Steel",
                    "S275",
                    "S355"
                ],
                "createdAt": "2024-07-12T09:57:27.540Z"
            },
            {
                "marketName": "Stainless Steel Manufacturers",
                "countries": [
                    "all"
                ],
                "keywords": [
                    "Stainless steel production"
                ],
                "createdAt": "2024-05-15T12:50:28.396Z"
            }
        ]
    }
}

Body Request Object Example

{
    "page": 1,
    "itemsPerPage": 5,
    "keyword": "",
    "collectionId": 123
}

Body

keyword

string

default:""

The Regular Expression string to search for a phrase or keyword within a Market’s name, description, or subtitle.

With a few notable exceptions below, this value can be treated as a case-insensitive string search for the market title.

Special Characters:

(Foo) - Due to these being capture groups in Regex, these will need to be escaped as \\(Some Text\\) if you want to search for literal (). Actual capture groups are not used by this endpoint, however you can still use them to define group patterns, such as (Stainless )?Steel (Manufacturer|Supplier).
[Foo] - Character Class. Square brackets are used to define a character class, which allows you to match any one of the characters inside the brackets. For example, [abc] matches either a, b, or c. If you want to search literal [Foo], escape the query as \\[Foo\\].
{Foo} - Quantifier. Curly braces are used as quantifiers to specify the number of times an element should be matched. For example, a{2,3} matches the letter a if it appears 2 or 3 times. To search for literal {Foo}, use \\{\\}.

NOTE It is highly unusual for market names to contain [] or {}.

company

string

default:""

The string to search for a phrase or keyword within a Company’s name, domain, or dunsNumber. If both keyword and company are provided, it will prioritise company search.

marketId

number

default:""

If you would data about a specific market, you can pass the marketId here.

hsCode

array

default:""

An array of HS Codes to filter the markets by.

page

number

default:""

The page to return from the paginated results

itemsPerPage

number

default:""

The number of markets to return per page

collectionId

number

default:""

The collection to search in.

If not specified, the user’s default collection will be used.

Response

meta

object

Pagination details and metadata about the search results.

Show meta

currentPage

number

The current page number.

itemsPerPage

number

The number of items per page.

totalItems

number

The total number of items in the search results.

totalPages

number

The total number of pages in the search results.

collectionId

number

The collection that this search was performed in.

This will still be provided if no collectionId was given as parameter, for the purpose of validation.

data

object

The body of the search response.

Show marketData

_id

string

Forestreet internal identifier for the market data.

marketId

number

The unique identifier for the market.

name

string

The name of the market.

subtitle

string

The subtitle of the market.

description

string

A brief description of the market, if the user had specified any.

headerImageUrl

string

The URL pointing to the market’s header image.

companyCount

number

The total number of companies in the market.

hsCodes

array

An array of HS Codes associated with the market.

These may not be populuated in earlier markets.

topMeanScore

number

The confidence score for the study. This is calculated by taking the mean of the top half of all confidence scores in the study.

This value can range from -1 to 3; but in practice it can be capped to 0 to 1 as values outside of this range are only meaningful academically.

This may not be populuated in earlier markets.

createdAt

date

The date when the market was originally created.

versionDate

date

The date when the market was last updated.

searchCriteria

array

An array of search criteria used to create the market.

As markets could be manually merged, this provides a way to keep track of the original searches that were used to create the market, e.g. to understand if a keyword had been searched for a specific country.

Show searchCriteria

marketName

string

The name of the market as provided for this search.

marketRole

string

The role of the market as provided for this search.

The current 4 possible values are:

manufacturer
distributor
service provider
consultant

Some markets were created before the market role feature was introduced. The market role for these markets would have been inferred from the market name after the fact - they would not have contributed to the search. A generic provider is sometimes used on older markets. This is no longer an acceptable input value for marketRole.

countries

array

An array of countries associated with this search instance.

keywords

array

An array of keywords associated with this search instance.

createdAt

date

The date when this particular search was performed.

{
    "meta": {
        "currentPage": 1,
        "itemsPerPage": 25,
        "totalItems": 13,
        "totalPages": 1,
        "collectionId": 123,
    },
    "data": {
        "_id": "6690ff4679b5056b6bedfab3",
        "marketId": 4815,
        "name": "Stainless Steel Manufacturers",
        "subtitle": "Stainless Steel Manufacturers",
        "description": "Externally created study",
        "headerImageUrl": "https://ailsa-study-thumbnails.s3.eu-west-2.amazonaws.com/default-thumbnail%402x.jpg",
        "companyCount": 30,
        "hsCodes": [
            "7202",
            "7218",
            "7221",
            "7222",
            "7223",
            "7224",
            "7225",
            "7226"
        ],
        "topMeanScore": 0.84506,
        "createdAt": "2024-07-12T09:57:27.000Z",
        "versionDate": "2024-07-12T10:02:46.976Z",
        "searchCriteria": [
            {
                "marketName": "Stainless Steel Manufacturers",
                "countries": [
                    "all"
                ],
                "keywords": [
                    "SHS",
                    "UC",
                    "Universal Beam",
                    "Structural Steel",
                    "S275",
                    "S355"
                ],
                "createdAt": "2024-07-12T09:57:27.540Z"
            },
            {
                "marketName": "Stainless Steel Manufacturers",
                "countries": [
                    "all"
                ],
                "keywords": [
                    "Stainless steel production"
                ],
                "createdAt": "2024-05-15T12:50:28.396Z"
            }
        ]
    }
}

Market Collections Suggest Market Name

curl --request POST \
  --url https://api.forestreet.com/markets/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "keyword": "<string>",
  "company": "<string>",
  "marketId": 123,
  "hsCode": [
    {}
  ],
  "page": 123,
  "itemsPerPage": 123,
  "collectionId": 123
}'

{
    "meta": {
        "currentPage": 1,
        "itemsPerPage": 25,
        "totalItems": 13,
        "totalPages": 1,
        "collectionId": 123,
    },
    "data": {
        "_id": "6690ff4679b5056b6bedfab3",
        "marketId": 4815,
        "name": "Stainless Steel Manufacturers",
        "subtitle": "Stainless Steel Manufacturers",
        "description": "Externally created study",
        "headerImageUrl": "https://ailsa-study-thumbnails.s3.eu-west-2.amazonaws.com/default-thumbnail%402x.jpg",
        "companyCount": 30,
        "hsCodes": [
            "7202",
            "7218",
            "7221",
            "7222",
            "7223",
            "7224",
            "7225",
            "7226"
        ],
        "topMeanScore": 0.84506,
        "createdAt": "2024-07-12T09:57:27.000Z",
        "versionDate": "2024-07-12T10:02:46.976Z",
        "searchCriteria": [
            {
                "marketName": "Stainless Steel Manufacturers",
                "countries": [
                    "all"
                ],
                "keywords": [
                    "SHS",
                    "UC",
                    "Universal Beam",
                    "Structural Steel",
                    "S275",
                    "S355"
                ],
                "createdAt": "2024-07-12T09:57:27.540Z"
            },
            {
                "marketName": "Stainless Steel Manufacturers",
                "countries": [
                    "all"
                ],
                "keywords": [
                    "Stainless steel production"
                ],
                "createdAt": "2024-05-15T12:50:28.396Z"
            }
        ]
    }
}

Quick Start

UI Components

Discover

Markets

Companies

Projects

Users

Body Request Object Example

Body

Response

Quick Start

UI Components

Discover

Markets

Companies

Projects

Users

​Body Request Object Example

​Body

​Response

Body Request Object Example

Body

Response