{
	"info": {
		"_postman_id": "8b9cad0e-1f20-4192-bff0-e1e043ce143d",
		"name": "SetuGeo API - Official Collection v1.1",
		"description": "Comprehensive Postman collection for the SetuGeo Platform. Includes all 10 endpoints, detailed search examples, and auto-token extraction.",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "01. Authentication",
			"item": [
				{
					"name": "Generate Bearer Token",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									"var jsonData = pm.response.json();",
									"if (jsonData.success && jsonData.data && jsonData.data.token) {",
									"    pm.collectionVariables.set(\"token\", jsonData.data.token);",
									"    console.log(\"Token auto-updated successfully!\");",
									"}"
								],
								"type": "text/javascript"
							}
						}
					],
					"request": {
						"method": "POST",
						"header": [],
						"body": {
							"mode": "formdata",
							"formdata": [
								{
									"key": "client_key",
									"value": "{{client_key}}",
									"type": "text"
								},
								{
									"key": "client_secret",
									"value": "{{client_secret}}",
									"type": "text"
								}
							]
						},
						"url": {
							"raw": "{{base_url}}/auth/token",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"auth",
								"token"
							]
						}
					},
					"response": [
						{
							"name": "Token Generated Successfully",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "formdata",
									"formdata": [
										{
											"key": "client_key",
											"value": "{{client_key}}",
											"type": "text"
										},
										{
											"key": "client_secret",
											"value": "{{client_secret}}",
											"type": "text"
										}
									]
								},
								"url": {
									"raw": "{{base_url}}/auth/token",
									"host": [
										"{{base_url}}"
									],
									"path": [
										"auth",
										"token"
									]
								}
							},
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [],
							"cookie": [],
							"body": "{\n    \"success\": true,\n    \"data\": {\n        \"token\": \"1|abcdef1234567890...\"\n    }\n}"
						}
					]
				}
			]
		},
		{
			"name": "02. Global Infrastructure",
			"item": [
				{
					"name": "List Regions",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Authorization",
								"value": "Bearer {{token}}",
								"type": "text"
							}
						],
						"url": {
							"raw": "{{base_url}}/regions",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"regions"
							]
						}
					},
					"response": [
						{
							"name": "Regions List Example",
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [],
							"cookie": [],
							"body": "{\n    \"success\": true,\n    \"data\": [\n        { \"id\": 1, \"name\": \"Asia\" },\n        { \"id\": 2, \"name\": \"Europe\" }\n    ],\n    \"meta\": { \"total\": 6, \"current_page\": 1 }\n}"
						}
					]
				},
				{
					"name": "List Sub-Regions",
					"item": [
						{
							"name": "All Sub-Regions",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/sub-regions",
									"host": ["{{base_url}}"],
									"path": ["sub-regions"]
								}
							},
							"response": []
						},
						{
							"name": "Filter by Region ID",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/sub-regions?region_id=1",
									"host": ["{{base_url}}"],
									"path": ["sub-regions"],
									"query": [{ "key": "region_id", "value": "1" }]
								}
							},
							"response": []
						}
					]
				},
				{
					"name": "List Timezones",
					"request": {
						"method": "GET",
						"header": [
							{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
						],
						"url": {
							"raw": "{{base_url}}/timezones?name=Kolkata",
							"host": ["{{base_url}}"],
							"path": ["timezones"],
							"query": [{ "key": "name", "value": "Kolkata" }]
						}
					},
					"response": []
				}
			]
		},
		{
			"name": "03. Countries & States",
			"item": [
				{
					"name": "List Countries",
					"item": [
						{
							"name": "All Countries",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/countries",
									"host": ["{{base_url}}"],
									"path": ["countries"]
								}
							},
							"response": []
						},
						{
							"name": "Filter by ISO2",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/countries?iso2=IN",
									"host": ["{{base_url}}"],
									"path": ["countries"],
									"query": [{ "key": "iso2", "value": "IN" }]
								}
							},
							"response": []
						}
					]
				},
				{
					"name": "List States",
					"item": [
						{
							"name": "States of Country (ID)",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/states?country_id=101",
									"host": ["{{base_url}}"],
									"path": ["states"],
									"query": [{ "key": "country_id", "value": "101" }]
								}
							},
							"response": []
						},
						{
							"name": "Search State by Name",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/states?name=Maharashtra",
									"host": ["{{base_url}}"],
									"path": ["states"],
									"query": [{ "key": "name", "value": "Maharashtra" }]
								}
							},
							"response": []
						}
					]
				}
			]
		},
		{
			"name": "04. Cities & Pincodes",
			"item": [
				{
					"name": "List Cities",
					"item": [
						{
							"name": "Cities by State ID",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/cities?state_id=51",
									"host": ["{{base_url}}"],
									"path": ["cities"],
									"query": [{ "key": "state_id", "value": "51" }]
								}
							},
							"response": []
						},
						{
							"name": "Search City by Name",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/cities?name=Mumbai",
									"host": ["{{base_url}}"],
									"path": ["cities"],
									"query": [{ "key": "name", "value": "Mumbai" }]
								}
							},
							"response": []
						}
					]
				},
				{
					"name": "List Pincodes",
					"item": [
						{
							"name": "Pincodes by City ID",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/pincodes?city_id=1024",
									"host": ["{{base_url}}"],
									"path": ["pincodes"],
									"query": [{ "key": "city_id", "value": "1024" }]
								}
							},
							"response": []
						},
						{
							"name": "Filter by Pincode Value",
							"request": {
								"method": "GET",
								"header": [
									{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
								],
								"url": {
									"raw": "{{base_url}}/pincodes?pincode=400001",
									"host": ["{{base_url}}"],
									"path": ["pincodes"],
									"query": [{ "key": "pincode", "value": "400001" }]
								}
							},
							"response": []
						}
					]
				},
				{
					"name": "Search Pincode (Comprehensive)",
					"request": {
						"method": "GET",
						"header": [
							{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
						],
						"url": {
							"raw": "{{base_url}}/pincodes/search?code=400001",
							"host": ["{{base_url}}"],
							"path": ["pincodes", "search"],
							"query": [{ "key": "code", "value": "400001" }]
						}
					},
					"response": [
						{
							"name": "Comprehensive Search Response",
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [],
							"cookie": [],
							"body": "{\n    \"success\": true,\n    \"data\": [\n        {\n            \"pincode\": \"400001\",\n            \"country\": { \"id\": 101, \"name\": \"India\", \"iso2\": \"IN\" },\n            \"state\": { \"id\": 51, \"name\": \"Maharashtra\" },\n            \"city\": { \"id\": 1024, \"name\": \"Mumbai\" },\n            \"latitude\": \"18.922\",\n            \"longitude\": \"72.834\"\n        }\n    ]\n}"
						}
					]
				}
			]
		},
		{
			"name": "05. Metrics & Usage",
			"item": [
				{
					"name": "Live API Usage Report",
					"request": {
						"method": "GET",
						"header": [
							{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
						],
						"url": {
							"raw": "{{base_url}}/user/usage",
							"host": ["{{base_url}}"],
							"path": ["user", "usage"]
						}
					},
					"response": [
						{
							"name": "Usage Report Example",
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [],
							"cookie": [],
							"body": "{\n    \"success\": true,\n    \"data\": {\n        \"plan_name\": \"PRO\",\n        \"total_credits\": 50000,\n        \"available_credits\": 42500,\n        \"recent_logs\": [\n            { \"endpoint\": \"/api/v1/pincode/search\", \"status\": 200, \"time\": \"2026-03-27 12:45:00\" }\n        ]\n    }\n}"
						}
					]
				}
			]
},
		{
			"name": "06. Geospatial Analysis",
			"item": [
				{
					"name": "Global Data Statistics (Free)",
					"request": {
						"method": "GET",
						"header": [
							{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
						],
						"url": {
							"raw": "{{base_url}}/geospatial/statistics",
							"host": ["{{base_url}}"],
							"path": ["geospatial", "statistics"]
						},
						"description": "Comprehensive statistics for countries, states, and cities. This endpoint does not consume credits."
					},
					"response": []
				},
				{
					"name": "Precise Distance Calculator",
					"request": {
						"method": "GET",
						"header": [
							{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
						],
						"url": {
							"raw": "{{base_url}}/geospatial/distance?lat1=18.922&lng1=72.834&lat2=28.613&lng2=77.209&unit=km",
							"host": ["{{base_url}}"],
							"path": ["geospatial", "distance"],
							"query": [
								{ "key": "lat1", "value": "18.922" },
								{ "key": "lng1", "value": "72.834" },
								{ "key": "lat2", "value": "28.613" },
								{ "key": "lng2", "value": "77.209" },
								{ "key": "unit", "value": "km" }
							]
						},
						"description": "Calculates the distance between two latitude/longitude points. This endpoint consumes 1 credit."
					},
					"response": []
				},
				{
					"name": "Radius-based Nearby Search",
					"request": {
						"method": "GET",
						"header": [
							{ "key": "Authorization", "value": "Bearer {{token}}", "type": "text" }
						],
						"url": {
							"raw": "{{base_url}}/geospatial/nearby?lat=19.076&lng=72.877&radius=100&type=city",
							"host": ["{{base_url}}"],
							"path": ["geospatial", "nearby"],
							"query": [
								{ "key": "lat", "value": "19.076" },
								{ "key": "lng", "value": "72.877" },
								{ "key": "radius", "value": "100" },
								{ "key": "type", "value": "city" }
							]
						},
						"description": "Searches for Cities or Pincodes within a specific radius. This endpoint consumes 1 credit."
					},
					"response": []
				}
			]
		}
	],
	"variable": [
		{ "key": "base_url", "value": "http://localhost:8000/api/v1" },
		{ "key": "client_key", "value": "YOUR_PUBLIC_KEY" },
		{ "key": "client_secret", "value": "YOUR_SECRET_KEY" },
		{ "key": "token", "value": "YOUR_BEARER_TOKEN" }
	]
}