REST API Reference

Relevant source files

The following files were used as context for generating this wiki page:

• src/api/server.ts
• frontend/src/services/api.ts
• plan.md
• README.md
• src/api/routes/sitemap.ts

The WhereIsLifeCheaper REST API provides a programmatic interface for accessing grocery price data, supermarket information, and cross-country cost comparisons. It serves as the primary data bridge between the PostgreSQL backend—populated by daily scrapers—and the React-based frontend dashboard.

The API is built using Node.js and Express.js, implementing a modular routing structure that handles authentication, product management, and scraper orchestration. It supports features such as currency conversion via exchange rates and canonical product matching for cross-border price analysis.

Sources: plan.md:12, README.md:16, src/api/server.ts:16-27

Architecture Overview

The API architecture follows a standard Express.js middleware pattern. It incorporates security via helmet, handles cross-origin requests with cors, and manages persistent user sessions using express-session backed by a PostgreSQL store (connect-pg-simple).

Request Flow

The diagram below illustrates how a request is processed through the system:

The API utilizes a connection pool to interact with the PostgreSQL database and includes a health check endpoint to monitor connectivity status.

Sources: src/api/server.ts:31-64, src/api/server.ts:91-106, plan.md:139-145

Endpoint Reference

Public Data Endpoints

These endpoints provide access to the core datasets of the project, including supported countries, active supermarkets, and historical price data.

Method	Endpoint	Description
GET	/api/countries	Retrieves a list of all supported countries (e.g., TR, ME, ES).
GET	/api/supermarkets	Lists supermarket chains and their configurations.
GET	/api/products	Searches the product catalog with optional category filters.
GET	/api/prices/latest	Gets the most recent price points for specified products.
GET	/api/prices/stats	Returns aggregate statistics for price data.
GET	/api/rates	Provides current exchange rates for currency conversion.
GET	/health	Returns system health and database connection status.

Sources: README.md:94-102, src/api/server.ts:153-167, frontend/src/services/api.ts:25-50

Canonical Product & Comparison Endpoints

Canonical products act as master identifiers to link similar products across different countries and supermarkets, enabling direct price comparisons.

Parameter	Type	Description
search	string	Optional query to filter canonical products by name.
limit	number	Maximum number of results for pagination.
offset	number	Number of records to skip.

Sources: plan.md:154-159, frontend/src/services/api.ts:55-65

Administrative Endpoints

Administrative endpoints are protected and require authentication (Google OAuth 2.0). They allow for manual scraper control and data mapping.

Method	Endpoint	Description
POST	/api/scraper/trigger	Manually starts a specific supermarket scraper or all scrapers.
GET	/api/scraper/status	Returns currently running scrapers and recent execution logs.
PUT	/api/canonical/link	Maps a supermarket-specific product to a canonical master product.
POST	/api/rates/sync	Manually triggers a synchronization of exchange rates from external APIs.

Sources: README.md:104-110, frontend/src/services/api.ts:145-165

SEO and Static Routes

The API server also handles dynamic generation of search engine optimization (SEO) files located at the root path.

• Sitemap: GET /sitemap.xml dynamically generates an XML sitemap based on the current list of countries in the database.
• Robots: GET /robots.txt provides instructions to web crawlers, allowing access to country pages while disallowing /admin/ and /api/ paths.

Sources: src/api/routes/sitemap.ts:8-30, src/api/routes/sitemap.ts:70-96

Error Handling

The API implements a global error handler that catches internal exceptions. In development mode, the response includes the error message; in production, it returns a generic "Internal Server Error" to avoid leaking system details.

// Error handler implementation
app.use((err: Error, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
  apiLogger.error('API Error:', err);
  res.status(500).json({
    error: 'Internal Server Error',
    message: config.api.env === 'development' ? err.message : 'An error occurred',
  });
});

Sources: src/api/server.ts:133-140

Conclusion

The REST API serves as the central orchestration layer for the WhereIsLifeCheaper system. By providing structured access to scraped price data and administrative tools for product mapping, it enables the frontend to deliver real-time cost-of-living comparisons across multiple international markets.