# Pincode location lookup

Resolve JioMart geographic metadata for a valid six-digit Indian PIN.

- Platform: [JioMart](https://docs.upscrape.com/docs/platforms/jiomart)
- Capability ID: `jiomart.location.pincode.lookup`
- Cost: 1 credit per request
- Maximum runtime: 30 seconds
- Execute endpoint: `POST https://data.upscrape.com/execute`

## Request

Use the exact public capability ID in the shared execute envelope.

```bash
curl --request POST \
  --url https://data.upscrape.com/execute \
  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: wait=30" \
  --data '{
  "input": {
    "pincode": "400001"
  },
  "capability": "jiomart.location.pincode.lookup"
}'
```

## Input

Provide one six-digit pincode with a nonzero first digit.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `pincode` | `string` | Yes | Postal code (PIN) that sets the delivery location. |

### Example input

```json
{
  "pincode": "400001"
}
```

## Response

Successful output is returned in `results[0].data`.

The response returns location metadata such as names, parents and coordinates where supplied.

A successful PIN lookup does not establish that JioMart serves the PIN or that any product is locally stocked there. Use fulfillment data for product-specific availability.

### Illustrative sample output

This example shows one response. Values and optional fields vary with the data available.

```json
{
  "data": [
    {
      "display_name": "400001",
      "error": {
        "code": "upstream_error",
        "message": "The requested data could not be retrieved. Try again later."
      },
      "lat_long": {
        "coordinates": [
          72.8919,
          18.6291
        ],
        "type": "Point"
      },
      "meta": {
        "685945f46c8c7aee3f3af605": {
          "mbv_config": [
            {
              "department": "Groceries",
              "min_basket_value": 99
            }
          ],
          "zone": "west"
        }
      },
      "meta_code": {
        "country_code": "IN",
        "currency": {
          "code": "INR",
          "name": "Indian Rupee",
          "symbol": "₹"
        },
        "deliverables": [
          "essential"
        ],
        "hierarchy": [
          {
            "display_name": "Pincode",
            "slug": "pincode"
          },
          {
            "display_name": "City",
            "slug": "city"
          },
          {
            "display_name": "State",
            "slug": "state"
          }
        ],
        "iso2": "IN",
        "iso3": "IND",
        "latitude": "28.6667",
        "longitude": "77.2167",
        "parent_id": null,
        "phone_code": "+91",
        "zone": "red"
      },
      "name": "400001",
      "parents": [
        {
          "display_name": "India",
          "name": "INDIA",
          "sub_type": "country",
          "uid": "64aff96f9ed6a9d76597c317"
        },
        {
          "display_name": "MAHARASHTRA",
          "name": "MAHARASHTRA",
          "sub_type": "state",
          "uid": "6851881c34bc6fd8a2874563"
        },
        {
          "display_name": "MUMBAI",
          "name": "MUMBAI",
          "sub_type": "city",
          "uid": "6851881c34bc6fd8a287497a"
        }
      ],
      "sub_type": "pincode",
      "uid": "6851881d34bc6fd8a2876b47"
    }
  ],
  "raw": {
    "data": [
      {
        "display_name": "400001",
        "error": {
          "code": "upstream_error",
          "message": "The requested data could not be retrieved. Try again later."
        },
        "lat_long": {
          "coordinates": [
            72.8919,
            18.6291
          ],
          "type": "Point"
        },
        "meta": {
          "685945f46c8c7aee3f3af605": {
            "mbv_config": [
              {
                "department": "Groceries",
                "min_basket_value": 99
              }
            ],
            "zone": "west"
          }
        },
        "meta_code": {
          "country_code": "IN",
          "currency": {
            "code": "INR",
            "name": "Indian Rupee",
            "symbol": "₹"
          },
          "deliverables": [
            "essential"
          ],
          "hierarchy": [
            {
              "display_name": "Pincode",
              "slug": "pincode"
            },
            {
              "display_name": "City",
              "slug": "city"
            },
            {
              "display_name": "State",
              "slug": "state"
            }
          ],
          "iso2": "IN",
          "iso3": "IND",
          "latitude": "28.6667",
          "longitude": "77.2167",
          "parent_id": null,
          "phone_code": "+91",
          "zone": "red"
        },
        "name": "400001",
        "parents": [
          {
            "display_name": "India",
            "name": "INDIA",
            "sub_type": "country",
            "uid": "64aff96f9ed6a9d76597c317"
          },
          {
            "display_name": "MAHARASHTRA",
            "name": "MAHARASHTRA",
            "sub_type": "state",
            "uid": "6851881c34bc6fd8a2874563"
          },
          {
            "display_name": "MUMBAI",
            "name": "MUMBAI",
            "sub_type": "city",
            "uid": "6851881c34bc6fd8a287497a"
          }
        ],
        "sub_type": "pincode",
        "uid": "6851881d34bc6fd8a2876b47"
      }
    ],
    "error": {
      "code": "upstream_error",
      "message": "The requested data could not be retrieved. Try again later."
    },
    "request_uuid": "bc6b14f23e853987e2df9b3763bbcdd4",
    "stormbreaker_uuid": "ea8fe6f0-d60e-4a9b-ab82-97834e973c84",
    "success": true
  }
}
```
### Illustrative output fields

Derived from the sample above for orientation only. These fields are not a fixed response schema.

| Path | Observed type | Example |
| --- | --- | --- |
| `data` | `array` | 1 items |
| `data` | `array` | 1 items |
| `raw` | `object` | 5 fields |
| `raw.data` | `array` | 1 items |
| `raw.error` | `object` | 2 fields |
| `raw.request_uuid` | `string` | bc6b14f23e853987e2df9b3763bbcdd4 |
| `raw.stormbreaker_uuid` | `string` | ea8fe6f0-d60e-4a9b-ab82-97834e973c84 |
| `raw.success` | `boolean` | true |

## Execution behavior

A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job.

## Related documentation

- [Authentication](https://docs.upscrape.com/docs/api/authentication)
- [Jobs and results](https://docs.upscrape.com/docs/api/jobs)
- [Errors and retries](https://docs.upscrape.com/docs/api/errors)
- [Idempotency](https://docs.upscrape.com/docs/api/idempotency)