# chota-org/justdial-api architecture

> Architecture diagram of the GitHub repository chota-org/justdial-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chota-org/justdial-api
- Repository: https://github.com/chota-org/justdial-api

## Overview

Vyapar Leads API aggregates Indian business-directory listings into normalized, deduplicated leads, with search and CSV export as its main user-facing results. The workflow runs from an API request through source selection, platform-specific extraction, and aggregation; Justdial also resolves popular categories. Scrapers normalize contact and location data and can expand searches by locality. The README documents five source platforms, API-key protection, rate limiting, source discovery, health checks, and CSV export. Some server and scraper code was only sampled, so unsourced runtime links are omitted.

Main entry points: [`src/scrapers/index.js`](https://github.com/chota-org/justdial-api/blob/main/src/scrapers/index.js) (Source aggregator), [`src/utils/normalizer.js`](https://github.com/chota-org/justdial-api/blob/main/src/utils/normalizer.js) (Input and contact normalization), [`src/scrapers/grotal.js`](https://github.com/chota-org/justdial-api/blob/main/src/scrapers/grotal.js) (Grotal scraper), [`src/scrapers/justdial.js`](https://github.com/chota-org/justdial-api/blob/main/src/scrapers/justdial.js) (Justdial scraper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_server["HTTP API<br/>[server.js]"]
  node_search_export["Search and CSV<br/>[server.js]"]
  node_service_endpoints["Health and sources<br/>[server.js]"]
end

subgraph group_harvest["Lead harvesting"]
  node_aggregator["Source aggregator<br/>[index.js]"]
end

subgraph group_enrichment["Query and quality"]
  node_normalizer["Input and contact normalization<br/>[normalizer.js]"]
  node_categories["Category lookup<br/>[categories.js]"]
  node_city_areas["City locality catalog<br/>[cityAreas.js]"]
  node_locality_queue["Locality discovery queue<br/>[dynamicLocality.js]"]
  node_relevance["Lead relevance filter<br/>[relevanceFilter.js]"]
end

subgraph group_directories["Directory sources"]
  node_justdial["Justdial scraper<br/>[justdial.js]"]
  node_grotal["Grotal scraper<br/>[grotal.js]"]
  node_indiamart["IndiaMART scraper<br/>[indiamart.js]"]
  node_tradeindia["TradeIndia scraper<br/>[tradeindia.js]"]
  node_sulekha["Sulekha scraper<br/>[sulekha.js]"]
end

node_client(("API client"))
node_justdial_site["Justdial"]
node_grotal_site["Grotal"]
node_indiamart_site["IndiaMART"]
node_tradeindia_site["TradeIndia"]
node_sulekha_site["Sulekha"]

node_client -->|"requests"| node_server
node_server -->|"routes search and export"| node_search_export
node_server -->|"serves endpoints"| node_service_endpoints
node_search_export -->|"dispatches searches"| node_aggregator
node_aggregator -->|"dispatches"| node_justdial
node_aggregator -->|"dispatches"| node_grotal
node_aggregator -->|"dispatches"| node_indiamart
node_aggregator -->|"dispatches"| node_tradeindia
node_aggregator -->|"dispatches"| node_sulekha
node_justdial -->|"extracts listings"| node_justdial_site
node_grotal -->|"extracts listings"| node_grotal_site
node_indiamart -->|"extracts listings"| node_indiamart_site
node_tradeindia -->|"extracts listings"| node_tradeindia_site
node_sulekha -->|"extracts listings"| node_sulekha_site
node_aggregator -->|"normalizes and deduplicates"| node_normalizer
node_aggregator -->|"filters leads"| node_relevance
node_justdial -->|"cleans listing data"| node_normalizer
node_grotal -->|"cleans listing data"| node_normalizer
node_indiamart -->|"cleans listing data"| node_normalizer
node_tradeindia -->|"cleans listing data"| node_normalizer
node_sulekha -->|"cleans listing data"| node_normalizer
node_justdial -->|"looks up categories"| node_categories
node_grotal -->|"discovers areas"| node_locality_queue
node_grotal -->|"uses fallback areas"| node_city_areas
node_indiamart -->|"discovers areas"| node_locality_queue
node_tradeindia -->|"discovers areas"| node_locality_queue
node_sulekha -->|"discovers areas"| node_locality_queue
node_search_export -->|"normalizes query"| node_normalizer

click node_server "https://github.com/chota-org/justdial-api/blob/main/src/server.js"
click node_search_export "https://github.com/chota-org/justdial-api/blob/main/src/server.js"
click node_service_endpoints "https://github.com/chota-org/justdial-api/blob/main/src/server.js"
click node_aggregator "https://github.com/chota-org/justdial-api/blob/main/src/scrapers/index.js"
click node_justdial "https://github.com/chota-org/justdial-api/blob/main/src/scrapers/justdial.js"
click node_grotal "https://github.com/chota-org/justdial-api/blob/main/src/scrapers/grotal.js"
click node_indiamart "https://github.com/chota-org/justdial-api/blob/main/src/scrapers/indiamart.js"
click node_tradeindia "https://github.com/chota-org/justdial-api/blob/main/src/scrapers/tradeindia.js"
click node_sulekha "https://github.com/chota-org/justdial-api/blob/main/src/scrapers/sulekha.js"
click node_normalizer "https://github.com/chota-org/justdial-api/blob/main/src/utils/normalizer.js"
click node_categories "https://github.com/chota-org/justdial-api/blob/main/src/utils/categories.js"
click node_city_areas "https://github.com/chota-org/justdial-api/blob/main/src/utils/cityAreas.js"
click node_locality_queue "https://github.com/chota-org/justdial-api/blob/main/src/utils/dynamicLocality.js"
click node_relevance "https://github.com/chota-org/justdial-api/blob/main/src/utils/relevanceFilter.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_search_export,node_service_endpoints,node_client toneBlue
class node_aggregator toneAmber
class node_normalizer,node_categories,node_city_areas,node_locality_queue,node_relevance toneMint
class node_justdial,node_grotal,node_indiamart,node_tradeindia,node_sulekha toneRose
class node_justdial_site,node_grotal_site,node_indiamart_site,node_tradeindia_site,node_sulekha_site toneIndigo
```

## Components

### API

- [HTTP API](https://github.com/chota-org/justdial-api/blob/main/src/server.js): `src/server.js`
- [Search and CSV](https://github.com/chota-org/justdial-api/blob/main/src/server.js): `src/server.js`
- [Health and sources](https://github.com/chota-org/justdial-api/blob/main/src/server.js): `src/server.js`

### Lead harvesting

- [Source aggregator](https://github.com/chota-org/justdial-api/blob/main/src/scrapers/index.js): `src/scrapers/index.js`

### Query and quality

- [Input and contact normalization](https://github.com/chota-org/justdial-api/blob/main/src/utils/normalizer.js): `src/utils/normalizer.js`
- [Category lookup](https://github.com/chota-org/justdial-api/blob/main/src/utils/categories.js): `src/utils/categories.js`
- [City locality catalog](https://github.com/chota-org/justdial-api/blob/main/src/utils/cityAreas.js): `src/utils/cityAreas.js`
- [Locality discovery queue](https://github.com/chota-org/justdial-api/blob/main/src/utils/dynamicLocality.js): `src/utils/dynamicLocality.js`
- [Lead relevance filter](https://github.com/chota-org/justdial-api/blob/main/src/utils/relevanceFilter.js): `src/utils/relevanceFilter.js`

### Directory sources

- [Justdial scraper](https://github.com/chota-org/justdial-api/blob/main/src/scrapers/justdial.js): `src/scrapers/justdial.js`
- [Grotal scraper](https://github.com/chota-org/justdial-api/blob/main/src/scrapers/grotal.js): `src/scrapers/grotal.js`
- [IndiaMART scraper](https://github.com/chota-org/justdial-api/blob/main/src/scrapers/indiamart.js): `src/scrapers/indiamart.js`
- [TradeIndia scraper](https://github.com/chota-org/justdial-api/blob/main/src/scrapers/tradeindia.js): `src/scrapers/tradeindia.js`
- [Sulekha scraper](https://github.com/chota-org/justdial-api/blob/main/src/scrapers/sulekha.js): `src/scrapers/sulekha.js`

### Other components

- **API client**
- **Justdial**
- **Grotal**
- **IndiaMART**
- **TradeIndia**
- **Sulekha**

## Connections

- API client → HTTP API: requests (evidence: `README.md`)
- HTTP API → Search and CSV: routes search and export (evidence: `src/server.js`)
- HTTP API → Health and sources: serves endpoints (evidence: `README.md`)
- Search and CSV → Source aggregator: dispatches searches (evidence: `src/server.js`)
- Source aggregator → Justdial scraper: dispatches (evidence: `src/scrapers/index.js`)
- Source aggregator → Grotal scraper: dispatches (evidence: `src/scrapers/index.js`)
- Source aggregator → IndiaMART scraper: dispatches (evidence: `src/scrapers/index.js`)
- Source aggregator → TradeIndia scraper: dispatches (evidence: `src/scrapers/index.js`)
- Source aggregator → Sulekha scraper: dispatches (evidence: `src/scrapers/index.js`)
- Justdial scraper → Justdial: extracts listings (evidence: `README.md`)
- Grotal scraper → Grotal: extracts listings (evidence: `src/scrapers/grotal.js`)
- IndiaMART scraper → IndiaMART: extracts listings (evidence: `README.md`)
- TradeIndia scraper → TradeIndia: extracts listings (evidence: `README.md`)
- Sulekha scraper → Sulekha: extracts listings (evidence: `README.md`)
- Source aggregator → Input and contact normalization: normalizes and deduplicates (evidence: `src/scrapers/index.js`)
- Source aggregator → Lead relevance filter: filters leads (evidence: `src/scrapers/index.js`)
- Justdial scraper → Input and contact normalization: cleans listing data (evidence: `src/scrapers/justdial.js`)
- Grotal scraper → Input and contact normalization: cleans listing data (evidence: `src/scrapers/grotal.js`)
- IndiaMART scraper → Input and contact normalization: cleans listing data (evidence: `src/scrapers/indiamart.js`)
- TradeIndia scraper → Input and contact normalization: cleans listing data (evidence: `src/scrapers/tradeindia.js`)
- Sulekha scraper → Input and contact normalization: cleans listing data (evidence: `src/scrapers/sulekha.js`)
- Justdial scraper → Category lookup: looks up categories (evidence: `src/scrapers/justdial.js`)
- Grotal scraper → Locality discovery queue: discovers areas (evidence: `src/scrapers/grotal.js`)
- Grotal scraper → City locality catalog: uses fallback areas (evidence: `src/scrapers/grotal.js`)
- IndiaMART scraper → Locality discovery queue: discovers areas (evidence: `src/scrapers/indiamart.js`)
- TradeIndia scraper → Locality discovery queue: discovers areas (evidence: `src/scrapers/tradeindia.js`)
- Sulekha scraper → Locality discovery queue: discovers areas (evidence: `src/scrapers/sulekha.js`)
- Search and CSV → Input and contact normalization: normalizes query (evidence: `src/server.js`)
