Skip to main content

Insight Scenarios

This guide details common use cases for the Insight API (/v6/intelligence/insight). This unified endpoint allows you to discover regions, generate reports, and check status using the insight_intent parameter.

1. Region Discovery​

Intent: region_discovery
Use this to find the region_id for a specific location or to explore the hierarchy (e.g., State -> District -> Village).

Scenario: Find districts in a State​

Get the children of a specific state (e.g., Maharashtra) to find a district's ID.

POST /v6/intelligence/insight
{
  "insight_intent": "region_discovery",
  "reference_id": "DISC_001",
  "insight_scope": [
    {
      "region_id": "35a3fd95-d301-4d12-803f-e20f31e2691d" // Maharashtra State ID
    }
  ],
  "insight_protocol": [{
    "depth": 1,
    "report_template_code": 1
  }]
}

2. Generate Report (Sync)​

Intent: report
Use this for instant report generation for small regions or single parcels. The response will contain the data directly.

Scenario: Get Crop Health for a Village​

Request a report for a specific region ID in sync mode.

POST /v6/intelligence/insight
{
  "insight_intent": "report",
  "reference_id": "REP_SYNC_001",
  "insight_scope": [
    {
      "unique_identifier": "1",
      "region_id": "105677d6-7213-478a-81c5-e3d1d1fed2e0"
    }
  ],
  "insight_protocol": [
    {
      "report_template_code": 1,
      "mode": "sync",
      "media_type": "json"
    }
  ]
}

3. Generate Report (Async)​

Intent: report
Use this for large batches or complex reports. The API will return an insight_id and status 1000 (Request Accepted). You must poll for results.

Scenario: Batch Report for Multiple Regions​

POST /v6/intelligence/insight
{
  "insight_intent": "report",
  "reference_id": "REP_ASYNC_001",
  "insight_scope": [
    { "unique_identifier": "1", "region_id": "105677d6-112e-416d-af1c-4b85db78cf73" },
    { "unique_identifier": "2", "region_id": "105677d6-5309-4828-9486-0f4cab4a1326" }
  ],
  "insight_protocol": [
    {
      "report_template_code": 1,
      "mode": "async",
      "callback_url": {
        "url": "https://your-webhook.com/callback"
      }
    }
  ]
}

4. Check Insight Status​

Intent: insight_status
Use this to check if your Async report is ready.

Scenario: Poll for completion​

POST /v6/intelligence/insight
{
  "insight_intent": "insight_status",
  "reference_id": "STATUS_001",
  "insight_scope": [], // Not required for status check if using reference_id
  "insight_protocol": []
}

Response (Success): Status code 2000 indicates the report is ready.