Retrieve Trade Metrics

GET /api/v1/trades/metrics

Description

This endpoint retrieves detailed metrics for trades, allowing for extensive analysis based on grouping, time ranges, and other filtering criteria. It is crucial for business intelligence, inventory management, and strategic planning.

Headers:

• tenantId (required): The tenant ID under which the trade metrics are queried. This identifies the specific tenant environment.
• userId (required): The user ID of the individual requesting the trade metrics.
• countryCode (required): The country code where the trades are conducted. This helps to filter metrics relevant to a specific geographical area.

Query Parameters:

• groupBy (required): Specifies the criteria for grouping the results. Options include CREATED_BY, DELETED_BY, UPDATED_BY, PRODUCT_ID, PRODUCT_USER, TRADE_PRODUCT_ID, TRADE_STATE, TRADE_CITY, TRADE_BUYER, TRADE_SELLER. Values should be separated by commas.
• metricDateRange (optional): Filters metrics by a specific date range. Format: start_date,end_date (e.g., 2020-11-12,2022-11-15).
• byValueType (optional): Specifies the type of value range used for filtering metrics. Necessary if byValue is used. Available options: HOUR, DAY, DAY_OF_WEEK, WEEK, MONTH.
• byValue (optional): A numerical value to filter metrics when used in conjunction with byValueType.
• tradeSearch (optional): A general search term to filter the metrics based on trade details.
• tradeStatuses (optional): Filters the trades by their current statuses. Options: ACTIVE, CLOSED, DRAFT, TERMINATED.
• tradeByProductIds (optional): Filters the metrics based on specific product IDs.
• tradeIds (optional): Filters the metrics based on specific trade IDs.
• byStates (optional): Filters trades by states.
• byCities (optional): Filters trades by cities.
• byBusinessIds (optional): Filters metrics by business IDs.

Example Request:

curl -G "http://[base_url]/api/v1/trades/metrics" \
     -H "Authorization: Bearer [access_token]" \
     -H "tenantId: TEN123" \
     -H "userId: USR456" \
     -H "countryCode: US" \
     -d "groupBy=PRODUCT_ID,TRADE_CITY" \
     -d "metricDateRange=2020-11-12,2022-11-15" \
     -d "byValueType=MONTH" \
     -d "byValue=12" \
     -d "tradeSearch=oil" \
     -d "tradeStatuses=ACTIVE" \
     -d "tradeByProductIds=123" \
     -d "tradeIds=1001" \
     -d "byStates=California" \
     -d "byCities=San Francisco" \
     -d "byBusinessIds=BIZ123"

Responses:

• 200 OK: Successfully retrieved the trade metrics. The response includes detailed data about the trades that match the specified criteria, potentially including sales trends, inventory levels, and other relevant metrics.

Example Response:

{
  "metrics": [
    {
      "groupBy": "PRODUCT_ID",
      "data": [
        {
          "productId": "123",
          "totalSales": 500,
          "remainingStock": 50
        }
      ]
    }
  ]
}

Error Responses:

• 400 Bad Request: Incorrect or incomplete query parameters.
• 404 Not Found: No metrics found based on the provided criteria.
• 403 Forbidden: The user does not have permission to view the metrics.