> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forestreet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Existing Markets

> Search the list of available markets.

### Body Request Object Example

```JSON theme={null}
{
    "page": 1,
    "itemsPerPage": 5,
    "keyword": "",
    "collectionId": 123
}
```

### Body

<ParamField body="keyword" type="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 `{}`.*
</ParamField>

<ParamField body="company" type="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.
</ParamField>

<ParamField body="marketId" type="number" default="">
  If you would data about a specific market, you can pass the marketId here.
</ParamField>

<ParamField body="hsCode" type="array" default="">
  An array of HS Codes to filter the markets by.
</ParamField>

<ParamField body="page" type="number" default="">
  The page to return from the paginated results
</ParamField>

<ParamField body="itemsPerPage" type="number" default="">
  The number of markets to return per page
</ParamField>

<ParamField body="collectionId" type="number" default="">
  The collection to search in.

  If not specified, the user's default collection will be used.
</ParamField>

### Response

<ResponseField name="meta" type="object">
  Pagination details and metadata about the search results.

  <Expandable title="meta">
    <ResponseField name="currentPage" type="number">
      The current page number.
    </ResponseField>

    <ResponseField name="itemsPerPage" type="number">
      The number of items per page.
    </ResponseField>

    <ResponseField name="totalItems" type="number">
      The total number of items in the search results.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      The total number of pages in the search results.
    </ResponseField>

    <ResponseField name="collectionId" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object">
  The body of the search response.

  <Expandable title="marketData">
    <ResponseField name="_id" type="string">
      Forestreet internal identifier for the market data.
    </ResponseField>

    <ResponseField name="marketId" type="number">
      The unique identifier for the market.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the market.
    </ResponseField>

    <ResponseField name="subtitle" type="string">
      The subtitle of the market.
    </ResponseField>

    <ResponseField name="description" type="string">
      A brief description of the market, if the user had specified any.
    </ResponseField>

    <ResponseField name="headerImageUrl" type="string">
      The URL pointing to the market's header image.
    </ResponseField>

    <ResponseField name="companyCount" type="number">
      The total number of companies in the market.
    </ResponseField>

    <ResponseField name="hsCodes" type="array">
      An array of HS Codes associated with the market.

      These may not be populuated in earlier markets.
    </ResponseField>

    <ResponseField name="topMeanScore" type="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.
    </ResponseField>

    <ResponseField name="createdAt" type="date">
      The date when the market was originally created.
    </ResponseField>

    <ResponseField name="versionDate" type="date">
      The date when the market was last updated.
    </ResponseField>

    <ResponseField name="searchCriteria" type="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.

      <Expandable title="searchCriteria">
        <ResponseField name="marketName" type="string">
          The name of the market as provided for this search.
        </ResponseField>

        <ResponseField name="marketRole" type="string">
          The role of the market as provided for this search.

          The current 4 possible values are:

          * `manufacturer`
          * `distributor`
          * `service provider`
          * `consultant`

          <Note>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`.</Note>
        </ResponseField>

        <ResponseField name="countries" type="array">
          An array of countries associated with this search instance.
        </ResponseField>

        <ResponseField name="keywords" type="array">
          An array of keywords associated with this search instance.
        </ResponseField>

        <ResponseField name="createdAt" type="date">
          The date when this particular search was performed.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
      "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"
              }
          ]
      }
  }
  ```
</ResponseExample>