import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "zudoku/ui/Card";
import { Button } from "zudoku/ui/Button";

## MCC-MNC API

The **MCC-MNC API** lets partners resolve mobile network operators by **MCC/MNC**, **PLMN**, **country ISO**, **dial code**, or **operator name**. Use it to enrich phone numbers, validate roaming data, or power operator lookup in your applications.

<div className="not-prose my-4">
  <Card>
    <CardContent className="pt-6">
      <div className="flex flex-wrap items-center gap-3">
        <Button asChild>
          <a href="/api/mcc-mnc">View API Documentation →</a>
        </Button>
        <span className="text-sm text-muted-foreground">
          Interactive reference, request/response schemas, and examples
        </span>
      </div>
      <p className="mt-3 text-sm text-muted-foreground">
        Use the <strong>Interactive Playground</strong> on the API reference page to test endpoints with your Console <code>client_id</code> and <code>client_secret</code>.
      </p>
    </CardContent>
  </Card>
</div>

**Base URL:** `https://api.omaxtelecom.com/tools/mcc-mnc/`

---

## What can you do?

| Capability | Endpoint | Description |
|------------|----------|-------------|
| **Operator lookup** | `POST /lookup` | Resolve a single operator by MCC+MNC or PLMN |
| **By country** | `POST /by-country` | List operators for an ISO country code or dial prefix |
| **Search** | `POST /search` | Search operators by name (min. 2 characters) |
| **Bulk lookup** | `POST /bulk/lookup` | Submit a batch lookup job (async) |
| **Job status** | `GET /bulk/lookup/{job}` | Poll bulk job progress and results |
| **Health** | `GET /health` | Check service availability (no auth) |

---

## Authentication

All endpoints except `/health` require OAuth 2.0 Client Credentials via **OmaxTelecom ID**:

```http
Authorization: Bearer <access_token>
```

Obtain a token from the shared OmaxTelecom API auth endpoint. This is **not** under the MCC-MNC base URL — see the [Auth API reference](/api/auth):

```
POST https://api.omaxtelecom.com/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
```

Get your `client_id` and `client_secret` from [OmaxTelecom Console](https://console.omaxtelecom.com).

---

## Billing

Each successful **lookup**, **by-country**, or **search** request is billed per your organisation's `price_per_request` via the Console Wallet API when the price is greater than zero.

| HTTP status | Error code | Meaning |
|-------------|------------|---------|
| `402` | `INSUFFICIENT_BALANCE` | Wallet balance too low |
| `403` | `MCC_MNC_DISABLED` | MCC-MNC API not enabled for your organisation |
| `403` | `BILLING_NOT_CONFIGURED` | Billing is not configured |
| `404` | `OPERATOR_NOT_FOUND` | No matching operator |

---

## Response envelope

Successful responses:

```json
{
  "success": true,
  "data": {
    "mcc": "242",
    "mnc": "99",
    "plmn": "24299",
    "region": "Europe",
    "country": "Norway",
    "iso": "NO",
    "dial_code": "+47",
    "dial_codes": ["+47"],
    "operator": "TampNet AS",
    "brand": null,
    "tadig": "NORTM",
    "bands": "LTE 800, LTE 1800"
  }
}
```

Error responses:

```json
{
  "success": false,
  "error": {
    "code": "OPERATOR_NOT_FOUND",
    "message": "No operator matched the request"
  }
}
```

### Operator object

| Field | Description |
|-------|-------------|
| `mcc` | Mobile Country Code |
| `mnc` | Mobile Network Code |
| `plmn` | Combined PLMN (MCC + MNC) |
| `region` | Geographic region |
| `country` | Country name |
| `iso` | ISO 3166-1 alpha-2 country code |
| `dial_code` | Primary international dial prefix |
| `dial_codes` | All dial prefixes for the country |
| `operator` | Network operator name |
| `brand` | Commercial brand (if different) |
| `tadig` | TADIG code (roaming) |
| `bands` | Supported frequency bands |

---

## Examples

### Lookup by MCC and MNC

```bash
curl -X POST "https://api.omaxtelecom.com/tools/mcc-mnc/lookup?mcc=242&mnc=99" \
  -H "Authorization: Bearer <access_token>"
```

**Response `200 OK`:**

```json
{
  "success": true,
  "data": {
    "mcc": "242",
    "mnc": "99",
    "plmn": "24299",
    "region": "Europe",
    "country": "Norway",
    "iso": "NO",
    "dial_code": "+47",
    "dial_codes": ["+47"],
    "operator": "TampNet AS",
    "brand": null,
    "tadig": "NORTM",
    "bands": "LTE 800, LTE 1800"
  }
}
```

**Response `404 Not Found`:**

```json
{
  "success": false,
  "error": {
    "code": "OPERATOR_NOT_FOUND",
    "message": "No operator matched the request"
  }
}
```

### Lookup by PLMN

```bash
curl -X POST "https://api.omaxtelecom.com/tools/mcc-mnc/lookup?plmn=24299" \
  -H "Authorization: Bearer <access_token>"
```

Returns the same operator object as the MCC+MNC lookup above.

### List operators in Norway

```bash
curl -X POST "https://api.omaxtelecom.com/tools/mcc-mnc/by-country?iso=NO" \
  -H "Authorization: Bearer <access_token>"
```

**Response `200 OK`:**

```json
{
  "success": true,
  "data": {
    "iso": "NO",
    "dial_code": "+47",
    "count": 2,
    "operators": [
      {
        "mcc": "242",
        "mnc": "01",
        "plmn": "24201",
        "region": "Europe",
        "country": "Norway",
        "iso": "NO",
        "dial_code": "+47",
        "dial_codes": ["+47"],
        "operator": "Telenor Norge AS",
        "brand": "Telenor",
        "tadig": "NORTM",
        "bands": "GSM 900, UMTS 2100, LTE 800"
      },
      {
        "mcc": "242",
        "mnc": "02",
        "plmn": "24202",
        "region": "Europe",
        "country": "Norway",
        "iso": "NO",
        "dial_code": "+47",
        "dial_codes": ["+47"],
        "operator": "Telia Norge AS",
        "brand": "Telia",
        "tadig": "NORTL",
        "bands": "GSM 900, UMTS 2100, LTE 800"
      }
    ]
  }
}
```

### Search operators by name

```bash
curl -X POST "https://api.omaxtelecom.com/tools/mcc-mnc/search?query=Telenor&iso=NO&limit=10" \
  -H "Authorization: Bearer <access_token>"
```

**Response `200 OK`:**

```json
{
  "success": true,
  "data": {
    "query": "Telenor",
    "iso": "NO",
    "limit": 10,
    "count": 1,
    "operators": [
      {
        "mcc": "242",
        "mnc": "01",
        "plmn": "24201",
        "region": "Europe",
        "country": "Norway",
        "iso": "NO",
        "dial_code": "+47",
        "dial_codes": ["+47"],
        "operator": "Telenor Norge AS",
        "brand": "Telenor",
        "tadig": "NORTM",
        "bands": "GSM 900, UMTS 2100, LTE 800"
      }
    ]
  }
}
```

### Bulk lookup

```bash
curl -X POST "https://api.omaxtelecom.com/tools/mcc-mnc/bulk/lookup" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"mcc": "242", "mnc": "01"}, {"plmn": "24299"}]}'
```

**Response `202 Accepted`:**

```json
{
  "success": true,
  "data": {
    "job_id": "9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c"
  }
}
```

Poll the job:

```bash
curl "https://api.omaxtelecom.com/tools/mcc-mnc/bulk/lookup/9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c" \
  -H "Authorization: Bearer <access_token>"
```

**Response `200 OK` (processing):**

```json
{
  "success": true,
  "data": {
    "job_id": "9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c",
    "status": "processing",
    "total_count": 2,
    "processed_count": 1,
    "failed_count": 0,
    "items": [
      {
        "plmn": "24201",
        "status": "completed",
        "result": {
          "mcc": "242",
          "mnc": "01",
          "plmn": "24201",
          "region": "Europe",
          "country": "Norway",
          "iso": "NO",
          "dial_code": "+47",
          "dial_codes": ["+47"],
          "operator": "Telenor Norge AS",
          "brand": "Telenor",
          "tadig": "NORTM",
          "bands": "GSM 900, UMTS 2100, LTE 800"
        },
        "error": null
      },
      {
        "plmn": "24299",
        "status": "pending",
        "result": null,
        "error": null
      }
    ]
  }
}
```

### Health check

```bash
curl "https://api.omaxtelecom.com/tools/mcc-mnc/health"
```

**Response `200 OK`:**

```json
{
  "ok": true,
  "timestamp": "2026-08-20T16:42:00+00:00"
}
```

---

## Getting started

1. Enable MCC-MNC access for your organisation in [OmaxTelecom Console](https://console.omaxtelecom.com).
2. Obtain an access token via **OmaxTelecom ID** using your `client_id` and `client_secret`.
3. Call `GET /health` to confirm the service is reachable.
4. Start with `POST /lookup` or `POST /search` for single lookups.
5. Use bulk endpoints when you need to process large operator lists asynchronously.

## API Documentation

<div className="not-prose my-6">
  <Card>
    <CardHeader>
      <CardTitle>Complete API Reference</CardTitle>
      <CardDescription>
        Explore all endpoints with interactive examples, schemas, and authentication details.
      </CardDescription>
    </CardHeader>
    <CardContent>
      <Button asChild>
        <a href="/api/mcc-mnc">View API Documentation →</a>
      </Button>
    </CardContent>
  </Card>
</div>

## Need Help?

Contact [support@omaxtelecom.com](mailto:support@omaxtelecom.com) for integration support.