{
  "openapi": "3.1.0",
  "info": {
    "title": "NRIWallah service directory API",
    "version": "1.0.0",
    "description": "Read-only public API for the NRIWallah service directory: businesses that serve Non-Resident Indians, checked before they are listed. Results are paid listings ordered by fit to the question, never by payment, and are not recommendations; every response carries a `disclosure` to pass on. Public fields only. Rate limit: 120 calls an hour per address. An MCP server with the same data answers at https://www.nriwallah.com/api/mcp.",
    "contact": { "url": "https://www.nriwallah.com/contact/" }
  },
  "servers": [{ "url": "https://www.nriwallah.com/api/directory/v1" }],
  "paths": {
    "/search": {
      "get": {
        "operationId": "searchBusinesses",
        "summary": "Search listed businesses",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Service id from /categories (for example property-care, documents, trades, food-catering)." },
          { "name": "country", "in": "query", "schema": { "type": "string", "enum": ["uk", "us", "uae", "gulf", "saudi", "canada", "australia", "singapore", "germany", "europe", "japan", "newzealand"] }, "description": "Where the customer lives." },
          { "name": "town", "in": "query", "schema": { "type": "string", "maxLength": 40 }, "description": "Town or city for a service where the customer lives; matched by name." },
          { "name": "state", "in": "query", "schema": { "type": "string", "maxLength": 4 }, "description": "Indian state code (ISO 3166-2:IN without IN-), for a job in India." },
          { "name": "facts", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated fact ids every result must state (for example remote,updates or veg,jain)." },
          { "name": "language", "in": "query", "schema": { "type": "string" }, "description": "Language code, for example hi, ta, gu." },
          { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 80 }, "description": "Other words to match." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 } }
        ],
        "responses": {
          "200": { "description": "Ranked results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } },
          "429": { "description": "Too many requests" }
        }
      }
    },
    "/business/{id}": {
      "get": {
        "operationId": "getBusiness",
        "summary": "One listed business",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^e[0-9a-f]{16}$" } }],
        "responses": {
          "200": { "description": "The business", "content": { "application/json": { "schema": { "type": "object", "properties": { "disclosure": { "type": "string" }, "business": { "$ref": "#/components/schemas/Business" } } } } } },
          "404": { "description": "Not in the directory now" }
        }
      }
    },
    "/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "Service, country, fact and language ids",
        "responses": { "200": { "description": "Ids and names", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResult": {
        "type": "object",
        "properties": {
          "disclosure": { "type": "string" },
          "filters": { "type": "object" },
          "total": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/Business" } },
          "nothing_found": { "type": "string", "description": "Present when nothing matches: where the reader can ask instead." }
        }
      },
      "Business": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "legal_name": { "type": "string" },
          "page": { "type": "string", "format": "uri", "description": "The listing's page on nriwallah.com." },
          "services": { "type": "array", "items": { "type": "string" } },
          "service_ids": { "type": "array", "items": { "type": "string" } },
          "description": { "type": "string" },
          "serves_customers_in": { "type": "array", "items": { "type": "string" } },
          "works_in_towns": { "type": "array", "items": { "type": "object" } },
          "also_online": { "type": "boolean" },
          "in_india": { "type": "array", "items": { "type": "string" } },
          "languages": { "type": "array", "items": { "type": "string" } },
          "business_says": { "type": "array", "items": { "type": "string" }, "description": "The business's own statements." },
          "registered": { "type": "object" },
          "registrations": { "type": "array", "items": { "type": "object" } },
          "checked": { "type": "object", "description": "What NRIWallah checked and when; not a review of the work." },
          "fca": { "type": "array", "items": { "type": "object" } },
          "adviser": { "type": ["object", "null"] },
          "reviews": { "type": "object", "description": "Published member reviews; an average only from three." },
          "contact": { "type": "array", "items": { "type": "object" } },
          "listed_since": { "type": "string" }
        }
      }
    }
  }
}
