POST
/
markets
/
search
Search Existing 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.
​
data
object
The body of the search response.
{
    "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"
            }
        ]
    }
}