Overview
AI-powered API that analyzes merchant/shop images and returns structured classification data including NPCI-compliant MCC codes.
Base URL: https://mcc.platform.irame.ai/api/v1
Content Type: multipart/form-data for upload endpoints
Response Format: JSON
Authentication
All /analyze endpoints require an API key passed in the x-api-key header. Keys are issued by administrators, have configurable expiry dates and usage limits, and are tracked per request.
x-api-key: mcc_xxxxxxxxxxxxxxxxxxxxxxxx
/health and /mcc-codes are unauthenticated reference endpoints.
Endpoints
GET
/api/v1/health
Health check — no authentication required
POST
/api/v1/analyze
Analyze one or more images of a single shop. Send every photo of a vendor in one request: you get one consolidated result.
qr_codes, soundboxes and card_machines are the unique set across all photos: every brand any photo shows, listed once.Headers
| Header | Value | |
|---|---|---|
x-api-key | Your API key | required |
Content-Type | multipart/form-data | required |
Request Body (multipart/form-data)
| Field | Type | Description |
|---|---|---|
images | File[] | 1-10 image files (JPEG, PNG, WebP). Max 10MB each. |
Response (200 OK)
{
"success": true,
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"analysis_mode": "single_shop",
"processing_time_ms": 2340,
"data": {
"shop_name": "Sharma General Store",
"is_actual_shop": "Yes",
"shop_structure": "Permanent",
"mobility": "Non-Movable",
"shop_board": "Hard Board",
"shop_status": "Open",
"glass_door": "No",
"shop_counter": "Yes",
"merchant_present": "Yes",
"gstin": "27AAPFU0939F1ZV",
"gstin_status": "Valid",
"nature_of_business": "General grocery and daily essentials retail store",
"shop_category": "Grocery & Food",
"shop_sub_category": "Kirana Store",
"business_category": "Kirana Store",
"mcc_code": "5411",
"mcc_description": "Grocery Stores, Supermarkets",
"qr_codes": {
"present": "Yes",
"total_count": 3,
"players": [{ "player": "PhonePe", "count": 2 }, { "player": "Paytm", "count": 1 }]
},
"soundboxes": { "present": "Yes", "total_count": 1, "players": [{ "player": "Paytm", "count": 1 }] },
"card_machines": { "present": "No", "total_count": 0, "players": [] },
"inventory": {
"stock_level": "Well-stocked",
"product_types": ["packaged snacks", "soft drinks", "rice bags"],
"shelving_display": "Yes",
"refrigeration": "Yes"
},
"black_image": "No",
"images": { "received": 3, "analyzed": 2, "black_image_indexes": [2] }
}
}
POST
/api/v1/analyze/batch
Analyze multiple different shops. Each image is a separate shop, and each result carries
image_index, its 1-based upload position. Several photos of one shop belong in /analyze: here they are never combined.Headers
| Header | Value | |
|---|---|---|
x-api-key | Your API key | required |
Content-Type | multipart/form-data | required |
GET
/api/v1/mcc-codes
List all NPCI MCC codes supported by the system — no authentication required.
Usage Examples
cURL — Single Shop
curl -X POST \
https://mcc.platform.irame.ai/api/v1/analyze \
-H "x-api-key: mcc_xxxxxxxxxxxxxxxxxxxxxxxx" \
-F "images=@shop_front.jpg" \
-F "images=@shop_signage.jpg"
Python
import requests
url = "https://mcc.platform.irame.ai/api/v1/analyze"
headers = {"x-api-key": "mcc_xxxxxxxxxxxxxxxxxxxxxxxx"}
files = [("images", open("shop.jpg", "rb"))]
response = requests.post(url, headers=headers, files=files)
data = response.json()
Error Codes
| Status | Meaning | Common Cause |
|---|---|---|
| 400 | Bad Request | No images uploaded, invalid file type, too many files |
| 401 | Unauthorized | Missing or invalid x-api-key |
| 403 | Forbidden | API key disabled or expired |
| 413 | Payload Too Large | Image exceeds 10MB limit |
| 429 | Too Many Requests | API key request or image quota exhausted |
| 500 | Server Error | Upstream AI service failure, processing error |
Limits
| Max images per request | 10 |
| Max file size | 10 MB per image |
| Supported formats | JPEG, PNG, WebP |
| Per-key overall limits | Set by administrator (requests + images) |
MCC Shop Image Analyzer v1.0.0 | Powered by Irame AI | MCC codes as per NPCI guidelines