### Example Python Usage (Conceptual)

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

Illustrates how to make a request to the search endpoint using Python. This is a conceptual example and would require an actual HTTP client library.

```python
# Conceptual Python example for making a search request
# This requires an HTTP client library like 'requests'

# import requests

# api_url = "YOUR_API_ENDPOINT/search"

# # Example 1: Keyword Search
# keyword_payload = {
#     "keywords": {
#         "must_all": ["technology", "software"]
#     },
#     "locations": {
#         "country": "USA"
#     },
#     "size": 50,
#     "columns": ["company_name", "website", "industry"]
# }

# response_keyword = requests.post(api_url, json=keyword_payload)
# print(response_keyword.json())

# # Example 2: Similarity Search
# similarity_payload = {
#     "domains": ["example.com", "anotherexample.org"],
#     "excludes": ["spam.com"],
#     "size": 10,
#     "columns": ["company_name", "similarity_score"]
# }

# response_similarity = requests.post(api_url, json=similarity_payload)
# print(response_similarity.json())

# # Example 3: Semantic Search
# semantic_payload = {
#     "semantic_input": "A leading AI company in California",
#     "size": 15,
#     "columns": ["company_name", "description", "location"]
# }

# response_semantic = requests.post(api_url, json=semantic_payload)
# print(response_semantic.json())

```

--------------------------------

### Python Request Example for Sublocations

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

Demonstrates how to use the Python 'requests' library to call the 'sublocations' API endpoint. It shows setting up the API URL, headers (including an API key), and the JSON payload with parameters like parent_level, parent_value, and index. The example also includes printing the JSON response.

```python
import requests

api_url = 'https://api.istari.ai/v1/sublocations'

headers = {
    'x-api-key': 'sk_api_key',
    'Content-Type': 'application/json'
}

payload = {
    "parent_level": "country", # this is the level of the parent location (it must be a string!!)
    "parent_value": "Germany", # this is the value of the parent location (it must be a string!!)
    "index": "webai*" # this is the index that you are looking for in the database (it must be a string!!)
}

response = requests.post(api_url, headers=headers, json=payload)
print(response.json())
```

--------------------------------

### Sublocations API Response Example

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

Provides an example of the JSON response structure returned by the 'sublocations' API endpoint when querying for sublocations of 'Germany'. It shows the 'locations' array containing state names, the 'level' indicating 'state', and the 'total_count' of sublocations found.

```json
{
    "locations": ["Nordrhein-Westfalen", "Bayern", "Baden-Württemberg", "Niedersachsen", "Hessen", "Berlin", "Rheinland-Pfalz", "Sachsen", "Schleswig-Holstein", "Thüringen", "Hamburg", "Brandenburg", "Sachsen-Anhalt", "Mecklenburg-Vorpommern", "Saarland", "Bremen"],
    "level": "state",
    "total_count": 16
}
```

--------------------------------

### Sublocations Endpoint API Documentation

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

Details the 'sublocations' endpoint for retrieving geographic subdivisions. It includes parameters for parent level and value, the Elasticsearch index, and provides a Python example for making the request. The response fields 'locations', 'level', and 'total_count' are also described.

```APIDOC
Endpoint: sublocations

Retrieves all child locations (“sublocations”) for a given parent level and value.

Parameters:
- parent_level (string) – Geographic hierarchy to drill into:
  - all – return every level of sublocation
  - country – states/regions within a country
  - state – regions/districts within a state
  - region – districts/municipalities within a region
  - district – municipalities within a district
  - municipality – localities within a municipality
- parent_value (string) – The name of the parent location (e.g. "Germany").
- index (string) – The Elasticsearch index or pattern to query (e.g. "webai*").

Response Fields:
- locations (array) – Array of sublocation names (e.g., Germany’s 16 states)
- level (string) – Granularity of returned locations ("state" when drilling into country)
- total_count (int) – Number of items in the `locations` array
```

--------------------------------

### Fetch Market Data

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

This snippet demonstrates how to use the fetch-market endpoint to retrieve specific market data for a list of domains. It includes setting up the API URL, headers with an API key, and a JSON payload specifying the domains and desired columns.

```python
import requests

api_url = 'https://api.istari.ai/v1/fetch-market' # this is the endpoint for the API Gateway
headers = {
    'x-api-key': 'sk_api_key', # api-key generated from AWS API Gateway, each company has their own api-key in the future
    'Content-Type': 'application/json'
}

payload = {
    "domains": ["peterconradconstruction.com", "istari.ai"], # this is the list of domains that you are looking for in the database (it must be a list of strings even for a single domain!!)
    "columns": [ # this is the list of columns that you are looking for in the database
      "domain",
      "country",
      "state",
      "title",
      "description",
      "keywords"
    ],
    "index": "webai*" # this is the index that you are looking for in the database (it must be a string)
}

response = requests.post(api_url, headers=headers, json=payload)
print(response.json())
```

--------------------------------

### Similarity Search with Domains and Keywords

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

Performs a similarity search to find companies based on a list of domains, keywords, and location filters. The response includes company data and search metadata for pagination.

```python
import requests

api_url = 'https://api.istari.ai/v1/search'
headers = {
    'x-api-key': 'sk_api_key',
    'Content-Type': 'application/json'
}

payload = {
        "domains": [],                                                                # this is the list of domains that you are looking for in the database (it must be a list of strings!! or None)
        "excludes": [],                                                                             # this is the list of domains that you want to exclude from the search (it must be a list of strings!!)
        "keywords": {"must_one": ["packaging"], "must_all": [], "must_not": []},
        "locations": {"country": ["United Kingdom"], "state": [], "region": []},
        "custom_filters": {"b2x": ["B2C", "B2B"]},                             # apply extra field-level constraints (e.g. `country`, `team.name`, `products.type`). Each key must be an allowed column, and its list of values becomes Elasticsearch `filter` clauses to precisely include or exclude documents.
        "index": "webai*",
        "size": 1,
        "semantic_input": None,                                                                     # this is the semantic input that you are looking for in the database (it must be a string!!), if not using it please set it to None
        "columns": [
            "domain",
            "country",
            "state",
            "title",
            "description",
            "keywords",
            "region_code"
        ],
        "pit_id": None,
        "search_after": [],                                                                         # cursor-based paging: use the last hit’s sort values to fetch the next batch. It’s more efficient and consistent than deep offsets.
    }

response = requests.post(api_url, headers=headers, json=payload)
print(response.json())
```

--------------------------------

### Market API MCP Search Endpoint Documentation

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

Details the 'search' endpoint for fetching company records. Supports similarity search using 'domains' or keyword search using 'keywords', 'locations', and 'custom_filters'. Also supports semantic search via 'semantic_input'. Specifies request parameters, response structure, and important usage notes.

```APIDOC
Endpoint: search

Description:
Fetches company records from Elasticsearch in two modes:
- Similarity (KNN) Search when you supply `domains`.
- Keyword Search when `domains` is empty, using `keywords`, `locations`, and `custom_filters`.
- Semantic (KNN) Search : when you apply `semantic_input`.

Request Parameters:
- `domains` (string[]): (Optional) Seed domains for embedding-based similarity search.
- `excludes` (string[]): (Optional) Domains to omit from results.
- `keywords` (object): Term filters (`must_one`, `must_all`, `must_not`).
- `locations` (object): Geographic filters (`country`, `state`, `region`, etc.).
- `custom_filters` (object): Field-level filters (must match allowed filter columns).
- `index` (string): Elasticsearch index or pattern (default: "webai*").
- `size` (integer): Number of results (1–100, default: 25).
- `columns` (string[]): Fields to return (defaults to the core output columns).
- `pit_id` (string): (Optional) Point-in-time ID for consistent pagination.
- `search_after` (any[]): (Optional) Cursor token from previous response for efficient, deep pagination.
- `semantic_input` (string): (Optional) The semantic input (as the user query).

Response Structure:
- `data`: Array of company objects containing the requested `columns`.
- `metadata`: Echoes your inputs (including `domains`, `keywords`, `locations`, `columns`), plus query details and timestamps.

Important Note:
The domains and semantic_input can only one of them are having value else it will trigger an error.
```

--------------------------------

### Istari Market API MCP Endpoints

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

Documentation for the Istari Market API MCP endpoints, including the search and api-usage endpoints.

```APIDOC
Endpoints:

1. Search Endpoint:
   - URL: https://api.istari.ai/v1/search
   - Method: POST
   - Description: Performs a similarity search to find companies based on provided criteria.
   - Request Body Parameters:
     - domains (list[str] | None): List of domains to search for.
     - excludes (list[str]): List of domains to exclude from the search.
     - keywords (dict): Keyword filters with 'must_one', 'must_all', and 'must_not' lists.
     - locations (dict): Location filters including 'country', 'state', and 'region'.
     - custom_filters (dict): Field-level constraints for filtering (e.g., {"b2x": ["B2C", "B2B"]}).
     - index (str): The index to search within (e.g., "webai*").
     - size (int): The number of results to return.
     - semantic_input (str | None): Semantic input for the search.
     - columns (list[str]): List of columns to include in the response.
     - pit_id (str | None): Pointer to the ID for cursor-based paging.
     - search_after (list): Sort values for cursor-based paging.
   - Response Data:
     - domain (str): The website domain.
     - country (str): Geographic country information.
     - state (str): Geographic state information.
     - title (str): Metadata title scraped from the site.
     - description (str): Metadata description scraped from the site.
     - keywords (list[str]): Metadata keywords scraped from the site.
     - region_code (str): Internal code for the region.
   - Response Metadata:
     - total_hits (int): Total number of matches found.
     - search_id (str): Unique identifier for the search.
     - search_input (dict): Echo of the request parameters.
     - query (dict): The Elasticsearch boolean query.
     - pit_id (str): Pointer to the ID for pagination.
     - search_after (list): Sort values for pagination.
     - start_time (str): Query start time.
     - end_time (str): Query end time.

2. API Usage Endpoint:
   - URL: https://api.istari.ai/v1/api-usage
   - Method: GET
   - Description: Checks the API usage of the user, returning the number of requests sent.
   - Response Body:
     - Contains user API usage data.

Premium Request Criteria:
- Including 'b2x', 'summary', 'summary_keywords', 'team', 'partnerships', 'products', 'structure', 'team.contact', 'team.name', 'team.position', 'team.cv', 'partnerships.relationship_type', 'structure.contact', 'structure.description', 'structure.location', 'structure.name', 'structure.type', 'partnerships.entity_name', 'products.name', 'products.main_features', 'products.pricing', 'products.type' columns in the payload.
- Including 'semantic_input' or 'domains' in the search endpoint payload.
```

--------------------------------

### Istaria Market API MCP - fetch-market Endpoint

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

Details the fetch-market endpoint for retrieving market data. It specifies the request parameters, including domains and columns, and outlines the structure of the JSON response, which includes 'data' and 'metadata' sections.

```APIDOC
Endpoint: fetch-market

Fetches market data for the exact domains you specify in the `domains` parameter—no fuzzy matching or similar-company lookups. Use the optional `columns` parameter to list the fields you want returned.

Request Parameters:
- `domains` (list of strings): The list of domains to query.
- `columns` (list of strings, optional): The specific fields to retrieve for each domain. If not provided, a default set of columns may be returned.
- `index` (string): The index to search within the database.

Available Columns:
Contact & Communications:
  - `all_mails`
  - `all_phones`
  - `main_contact_mail`
  - `main_contact_number`
  - `links`
  - `address`

Domain Information:
  - `domain`
  - `domain_alias`
  - `domain_provider_true`
  - `domain_redirect`

Business Details:
  - `title`
  - `description`
  - `keywords`
  - `name`
  - `summary`
  - `summary_keywords`
  - `new_register_entry`
  - `type`
  - `b2x`
  - `techstack`

Location Data:
  - `continent`
  - `country` / `country_code`
  - `region` / `region_code`
  - `state` / `state_code`
  - `district` / `district_code`
  - `municipality` / `municipality_code`
  - `geolocation` _(includes `lat`, `lon`)_

Scores & Categories:
  - `cultural_score` / `cultural_score_category`
  - `leisure_score` / `leisure_score_category`
  - `recreational_score` / `recreational_score_category`
  - `transport_score` / `transport_score_category`

Probabilities & Classes:
  - `innoprob` / `innoprob_innovator_probability`
  - `social_innoprob` / `social_innoprob_innovator_probability`
  - `news_probability`
  - `retailer_probability`
  - `employee_class`
  - `revenue_class`

Intensity Metrics:
  AI:
    - `ai_intensity` / `ai_intensity_level`
    - `ai_keywords` / `ai_keywords_hits` / `ai_total_hits`
  
  Energy:
    - `energy_intensity` / `energy_intensity_level`
    - `energy_keywords` / `energy_keywords_hits` / `energy_total_hits`
  
  Sustainability:
    - `sustainability_intensity` / `sustainability_intensity_level`
    - `sustainability_keywords` / `sustainability_keywords_hits` / `sustainability_total_hits`
  
  Digital Health:
    - `digital_health_intensity` / `digital_health_intensity_level`
    - `digital_health_keywords` / `digital_health_keywords_hits` / `digital_health_total_hits`
  
  Mobility:
    - `mobility_intensity` / `mobility_intensity_level`
    - `mobility_keywords` / `mobility_keywords_hits` / `mobility_total_hits`
  
  Blockchain:
    - `blockchain_intensity` / `blockchain_intensity_level`
    - `blockchain_keywords` / `blockchain_keywords_hits` / `blockchain_total_hits`
  
  Additive Manufacturing:
    - `additive_manufacturing_intensity` / `additive_manufacturing_intensity_level`
    - `additive_manufacturing_keywords` / `additive_manufacturing_keywords_hits` / `additive_manufacturing_total_hits`
  
  SDG Metrics:
    - `sdg1_intensity` / `sdg1_intensity_level` / `sdg1_keywords` / `sdg1_keywords_hits` / `sdg1_total_hits`
    - `sdg2_intensity` / `sdg2_intensity_level` / `sdg2_keywords` / `sdg2_keywords_hits` / `sdg2_total_hits`
    - `sdg3_intensity` / `sdg3_intensity_level` / `sdg3_keywords` / `sdg3_keywords_hits` / `sdg3_total_hits`

Complex Structures:
  - `products` (contains: `name`, `type`, `pricing`, `main_features`)
  - `team` (contains: `name`, `position`, `contact`, `cv`)
  - `structure` (contains: `name`, `type`, `description`, `location`, `contact`)
  - `partnerships` (contains: `entity_name`, `relationship_type`)

Response Structure:
1. `data` (array of objects): Each object represents a queried domain and contains the requested columns.
   - `domain`: The queried domain name.
   - `country`: Registered/operating country.
   - `state`: State or region.
   - `title`: Content of the HTML `<title>` tag.
   - `description`: Content of the HTML `<meta name="description">` tag (or a snippet).
   - `keywords`: Content of the HTML `<meta name="keywords">` tag (empty string if absent).
2. `metadata` (object): Contains metadata about the API response.
```

--------------------------------

### API Usage Check

Source: https://github.com/istariai/market-api-mcp/blob/main/documentation-api-key.md

Retrieves the API usage statistics for the authenticated user, indicating the number of requests made.

```python
import requests

api_url = 'https://api.istari.ai/v1/api-usage'
headers = {
    'x-api-key': 'sk_api_key',
    'Content-Type': 'application/json'
}
response = requests.get(api_url, headers=headers)
print(response.json())
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.