MCC Shop Analyzer API

Web App Swagger UI Endpoints Examples Errors

Overview

AI-powered API that analyzes merchant/shop images and returns structured classification data including NPCI-compliant MCC codes. Powered by Irame AI vision models for fast, accurate analysis.

Base URL: https://mcc.platform.irame.ai/api/v1

Content Type: multipart/form-data for upload endpoints

Response Format: JSON

Authentication: None — endpoints are currently open.

Endpoints

GET /api/v1/health
Health check — no authentication required

Response

{
  "status": "healthy",
  "timestamp": "2026-04-15T10:30:00.000Z",
  "version": "1.0.0"
}
POST /api/v1/analyze
Analyze one or more images of a single shop. Upload multiple angles/views of the same shop for better accuracy.

Headers

HeaderValue
Content-Typemultipart/form-datarequired

Request Body (multipart/form-data)

FieldTypeDescription
imagesFile[]1-10 image files (JPEG, PNG, WebP). Max 10MB each. required

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",
    "mobility": "Non-Movable",
    "shop_board": "Hard Board",
    "shop_status": "Open",
    "nature_of_business": "General grocery and daily essentials retail store",
    "mcc_code": "5411",
    "mcc_description": "Grocery Stores, Supermarkets"
  }
}
POST /api/v1/analyze/batch
Analyze multiple different shops. Each image is treated as a separate shop.

Headers

HeaderValue
Content-Typemultipart/form-datarequired

Request Body (multipart/form-data)

FieldTypeDescription
imagesFile[]1-10 image files, each a different shop. required

Response (200 OK)

{
  "success": true,
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "analysis_mode": "multiple_shops",
  "processing_time_ms": 4520,
  "total_shops": 2,
  "data": [
    {
      "shop_name": "Sharma General Store",
      "is_actual_shop": "Yes",
      "mobility": "Non-Movable",
      "shop_board": "Hard Board",
      "shop_status": "Open",
      "nature_of_business": "General grocery and daily essentials retail store",
      "mcc_code": "5411",
      "mcc_description": "Grocery Stores, Supermarkets"
    },
    {
      "shop_name": "Raj Medical",
      "is_actual_shop": "Yes",
      "mobility": "Non-Movable",
      "shop_board": "Banner",
      "shop_status": "Open",
      "nature_of_business": "Pharmaceutical retail and prescription medicines",
      "mcc_code": "5912",
      "mcc_description": "Drug Stores and Pharmacies"
    }
  ]
}
GET /api/v1/mcc-codes
List all NPCI MCC codes supported by the system (deduplicated — each entry lists every category label that maps to it).

Response (200 OK)

{
  "success": true,
  "total": 42,
  "mcc_codes": [
    {
      "mcc": "5411",
      "description": "Grocery Stores, Supermarkets",
      "sample_categories": ["Grocery Store", "Supermarket"]
    }
  ]
}

Response Fields Reference

FieldTypeValuesDescription
shop_namestring—Name on shop signage (English transliteration)
is_actual_shopstringYesNoWhether the image shows a real physical shop
mobilitystringMovableNon-MovablePermanent structure vs. mobile/temporary setup
shop_boardstringBannerHard BoardNo BoardType of signage — flex/vinyl, permanent sign, or none
shop_statusstringOpenClosedWhether the shop appears operational in the image
nature_of_businessstring—Descriptive text (5-15 words) of the business
mcc_codestring4-digitNPCI Merchant Category Code
mcc_descriptionstring—Official MCC description as per NPCI

Usage Examples

cURL — Single Shop

curl -X POST \
  https://mcc.platform.irame.ai/api/v1/analyze \
  -F "images=@shop_front.jpg" \
  -F "images=@shop_signage.jpg"

cURL — Multiple Shops (Batch)

curl -X POST \
  https://mcc.platform.irame.ai/api/v1/analyze/batch \
  -F "images=@shop1.jpg" \
  -F "images=@shop2.jpg" \
  -F "images=@shop3.jpg"

Python

import requests

url = "https://mcc.platform.irame.ai/api/v1/analyze"
files = [("images", open("shop.jpg", "rb"))]

response = requests.post(url, files=files)
data = response.json()

print(f"Shop: {data['data']['shop_name']}")
print(f"MCC:  {data['data']['mcc_code']} - {data['data']['mcc_description']}")

JavaScript (fetch)

const formData = new FormData();
formData.append('images', fileInput.files[0]);

const response = await fetch('https://mcc.platform.irame.ai/api/v1/analyze', {
  method: 'POST',
  body: formData
});

const result = await response.json();
console.log(result.data);

Node.js

const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('images', fs.createReadStream('shop.jpg'));

const response = await fetch('https://mcc.platform.irame.ai/api/v1/analyze', {
  method: 'POST',
  body: form,
  headers: form.getHeaders()
});

Error Codes

StatusMeaningCommon Cause
400Bad RequestNo images uploaded, invalid file type, too many files
413Payload Too LargeImage exceeds 10MB limit
500Server ErrorUpstream AI service failure, processing error

Limits

Max images per request10
Max file size10 MB per image
Supported formatsJPEG, PNG, WebP
Backend throughputUp to 1,800 requests/min; no daily cap; excess queues with exponential backoff
MCC Shop Image Analyzer v1.0.0 | Powered by Irame AI | MCC codes as per NPCI guidelines