Skip to main content

Shop Website API Documentation

Overview​

This document catalogs all APIs used by the Villa Market e-commerce website (shop.villamarket.com). These APIs handle product catalog, search, inventory, pricing, promotions, authentication, and various integrations.

Base URL​

  • Production: https://shop.villamarket.com

API Categories​

1. Catalog & Product APIs​

Get Catalog Tree​

Retrieves the hierarchical catalog structure.

Endpoint: GET /api/v2/catalog-tree/catalog-tree

Description: Returns the complete product catalog tree structure.

Example Request:

GET https://shop.villamarket.com/api/v2/catalog-tree/catalog-tree

Get Sticky Banner​

Retrieves sticky banner configuration.

Endpoint: GET /api/v2/catalog-tree/sticky-banner

Description: Returns sticky banner data for display on the website.

Example Request:

GET https://shop.villamarket.com/api/v2/catalog-tree/sticky-banner

Get Banner Tree​

Retrieves banner tree structure.

Endpoint: GET /api/v2/catalog-tree/banner-tree

Description: Returns banner tree configuration for homepage and category pages.

Example Request:

GET https://shop.villamarket.com/api/v2/catalog-tree/banner-tree

Get Product List (Online Data)​

Retrieves product listing data.

Endpoint: GET /api/product/productlist/onlineData

Description: Returns product list data for online display.

Example Request:

GET https://shop.villamarket.com/api/product/productlist/onlineData

2. Search APIs​

Performs semantic search for products.

Endpoint: GET /api/search2/semantic_search

Query Parameters:

  • query (string, required): Search query string

Description: Returns search results based on semantic search algorithm.

Example Request:

GET https://shop.villamarket.com/api/search2/semantic_search?query=milk

Example Response: Returns product search results matching the query.

3. Product Group APIs​

Get Group Details​

Retrieves details for a product group.

Endpoint: GET /api/group/read/{groupId}

Path Parameters:

  • groupId (string, required): Product group ID (e.g., 7000000000, 7000000005)

Description: Returns detailed information about a specific product group.

Example Request:

GET https://shop.villamarket.com/api/group/read/7000000000

Get Group Image​

Retrieves product group images.

Endpoint: GET /api/group/image/{groupId}/{imageId}

Path Parameters:

  • groupId (string, required): Product group ID
  • imageId (string, required): Image identifier (e.g., {groupId}-1, {groupId}-2)

Description: Returns product group images. Supports various formats including .webp.

Example Request:

GET https://shop.villamarket.com/api/group/image/8000003683/8000003683-1
GET https://shop.villamarket.com/api/group/image/5000000102/5000000102-1.webp

4. Inventory APIs​

Get Inventory​

Retrieves inventory information.

Endpoint: GET /api/inventory2/{branchId}

Path Parameters:

  • branchId (string, required): Branch/store ID (e.g., 1000)

Query Parameters:

  • timestamp (number, optional): Timestamp for cache busting

Description: Returns inventory data for a specific branch.

Example Request:

GET https://shop.villamarket.com/api/inventory2/1000?timestamp=1762684762

5. Pricing APIs​

Get All Prices (GZ)​

Retrieves compressed price data.

Endpoint: POST /api/price/getallgz

Method: POST

Description: Returns compressed (gzip) price data for all products. This is likely used for bulk price updates.

Example Request:

POST https://shop.villamarket.com/api/price/getallgz
Content-Type: application/json

Note: Price data is also available from S3 bucket price-bucket-dev-manual with signed URLs.

6. Promotion APIs​

Get Promotion (Two for Four)​

Retrieves promotion data for "two for four" deals.

Endpoint: GET /api/promotion/get-two4

Query Parameters:

  • groupId (string, required): Promotion group ID (e.g., 9000000163)

Description: Returns promotion details for specific promotion groups.

Example Request:

GET https://shop.villamarket.com/api/promotion/get-two4?groupId=9000000163

7. Authentication APIs​

Invalidate Session​

Invalidates user session.

Endpoint: POST /auth/invalidate/invalidate

Method: POST

Description: Invalidates the current user session.

Example Request:

POST https://shop.villamarket.com/auth/invalidate/invalidate

Get API Key​

Retrieves API key for authenticated requests.

Endpoint: GET /auth/apikey/get

Query Parameters:

  • AWS Signature v4 parameters (X-Amz-Algorithm, X-Amz-Credential, X-Amz-Date, X-Amz-Expires, X-Amz-SignedHeaders, X-Amz-Signature, X-Amz-Security-Token)

Description: Returns API key for making authenticated API requests. Uses AWS Signature Version 4 for authentication.

Example Request:

GET https://shop.villamarket.com/auth/apikey/get?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...

Authentication: Uses AWS Cognito Identity for authentication.

8. Configuration & Schema APIs​

Get App First Page Config​

Retrieves first page configuration.

Endpoint: GET /app-first-page.json

Description: Returns configuration data for the first page/app initialization.

Example Request:

GET https://shop.villamarket.com/app-first-page.json

Get Schema Config​

Retrieves schema configuration from schema service.

Endpoint: GET https://schema.villamarket.com/villaMasterSchema/master/webData/config.yaml

Description: Returns YAML configuration schema for the web application.

Example Request:

GET https://schema.villamarket.com/villaMasterSchema/master/webData/config.yaml

Get First Page Category Schema​

Retrieves category schema for first page.

Endpoint: GET https://schema.villamarket.com/villaMasterSchema/master/webData/firstPageCat.yaml

Description: Returns category configuration schema for homepage.

Example Request:

GET https://schema.villamarket.com/villaMasterSchema/master/webData/firstPageCat.yaml

9. AWS Service Integrations​

AWS Cognito Identity​

Used for user authentication and identity management.

Endpoint: POST https://cognito-identity.ap-southeast-1.amazonaws.com/

Region: ap-southeast-1

Description: AWS Cognito Identity service for managing user identities and providing temporary AWS credentials.

Usage: Called multiple times during authentication flow to obtain identity credentials.

AWS Pinpoint​

Used for analytics and user engagement.

Endpoints:

  • PUT /v1/apps/{appId}/endpoints/{endpointId} - Update user endpoint
  • POST /v1/apps/{appId}/events - Track events

Base URL: https://pinpoint.ap-southeast-1.amazonaws.com

Region: ap-southeast-1

App ID: cc946a10031a4dabb6824d42fc6d2adb

Description: AWS Pinpoint for analytics, push notifications, and user engagement tracking.

Example Request:

PUT https://pinpoint.ap-southeast-1.amazonaws.com/v1/apps/cc946a10031a4dabb6824d42fc6d2adb/endpoints/{endpointId}

AWS API Gateway (Chat Service)​

Used for customer chat/communication.

Endpoint: GET https://ccia7fz3sl.execute-api.ap-southeast-1.amazonaws.com/production/rooms/customer/{userId}

Path Parameters:

  • userId (string, required): Cognito user ID (format: ap-southeast-1:{uuid})

Description: API Gateway endpoint for managing customer chat rooms.

Example Request:

GET https://ccia7fz3sl.execute-api.ap-southeast-1.amazonaws.com/production/rooms/customer/ap-southeast-1:5bf33d9a-8769-cf54-fc04-c10454b8ad29

10. S3 Storage APIs​

Product Images (Group 2 Image Bucket)​

Stores product group images.

Base URL: https://group2-image-bucket-dev.s3.ap-southeast-1.amazonaws.com or https://group2-image-bucket-dev.s3-ap-southeast-1.amazonaws.com

Path Pattern: /{groupId}/{imageId}

Description: S3 bucket storing product group images. Uses signed URLs for access.

Example URLs:

https://group2-image-bucket-dev.s3.ap-southeast-1.amazonaws.com/8000003684/8000003684-2
https://group2-image-bucket-dev.s3.ap-southeast-1.amazonaws.com/8000003684/8000003684-1
https://group2-image-bucket-dev.s3-ap-southeast-1.amazonaws.com/9000000162/9000000162-1.png

Price Data Bucket​

Stores compressed price data.

Base URL: https://price-bucket-dev-manual.s3-accelerate.amazonaws.com

Path Pattern: /{branchId}.gz

Description: S3 bucket storing compressed price data files. Uses S3 Transfer Acceleration and signed URLs.

Example URL:

https://price-bucket-dev-manual.s3-accelerate.amazonaws.com/1000.gz?AWSAccessKeyId=...&Signature=...

11. CDN & Image Delivery​

CloudFront CDN​

Content delivery network for product images.

Base URL: https://d1vl5j0v241n75.cloudfront.net

Path Pattern: /{productId} or /{productId}-{variant}

Description: CloudFront distribution for fast delivery of product images.

Example URLs:

https://d1vl5j0v241n75.cloudfront.net/0251806
https://d1vl5j0v241n75.cloudfront.net/0259653-0
https://d1vl5j0v241n75.cloudfront.net/0259703-1

12. Third-Party Analytics & Tracking​

Google Analytics​

  • Google Analytics 4: G-F11ZE3LE26
  • Universal Analytics: UA-203789938-1
  • Google Tag Manager: GTM-WJPPBZ3
  • Google Ads Conversion: AW-784182323, AW-16550547673

Endpoints:

  • https://www.google-analytics.com/analytics.js
  • https://analytics.google.com/g/collect
  • https://www.googletagmanager.com/gtm.js
  • Various conversion tracking endpoints

Description: Google Analytics and Google Tag Manager for website analytics and conversion tracking.

Facebook Pixel​

Facebook tracking pixel for advertising and analytics.

Pixel IDs:

  • 391632051329402 (Primary)
  • 984149833302230 (Secondary)

Endpoints:

  • https://connect.facebook.net/en_US/fbevents.js
  • https://www.facebook.com/tr/
  • https://connect.facebook.net/signals/config/

Description: Facebook Pixel for tracking conversions and building custom audiences.

Hotjar​

User behavior analytics.

Endpoint: https://static.hotjar.com/c/hotjar-1883266.js

Site ID: 1883266

Description: Hotjar for heatmaps, session recordings, and user feedback.

LINE Tag​

LINE marketing tag for tracking.

Endpoint: https://d.line-scdn.net/n/line_tag/public/release/v1/lt.js

Tracking Endpoint: https://tr.line.me/tag.gif

Description: LINE Tag for tracking LINE-related conversions and user behavior.

AppsFlyer​

Mobile attribution and analytics.

Endpoint: https://websdk.appsflyer.com/

Description: AppsFlyer SDK for mobile app attribution and analytics.

13. Static Assets​

Category Images​

Category icon images.

Base URL: https://shop.villamarket.com/public/image/category/

File Patterns:

  • beef.webp
  • pork.webp
  • chicken.webp
  • lamb.webp
  • seafood.webp
  • delicatessen.webp
  • frozen-food.webp
  • dairy.webp
  • bakery.webp
  • fruit_new.webp
  • veg.webp
  • onlyatvilla.webp
  • new-arrival.webp
  • special-offer.webp
  • best-seller.webp
  • health.webp
  • grocery.webp
  • confectionery.webp
  • drinks.webp
  • baby.webp
  • pet.webp
  • beauty.webp
  • grab-go.webp
  • partnership-shops.webp
  • gourmet-line.webp
  • pre-order.webp
  • buy-again.webp

Description: Static category icon images served from the public directory.

Flags API​

Country flag images for product origin display.

Base URL: https://flagsapi.com/{countryCode}/flat/64.png

Description: External API for country flag images (used for displaying product origin).

Example URLs:

https://flagsapi.com/GB/flat/64.png
https://flagsapi.com/TH/flat/64.png
https://flagsapi.com/US/flat/64.png

API Request Patterns​

Authentication Flow​

  1. User authenticates via AWS Cognito Identity
  2. Obtain API key via /auth/apikey/get with AWS Signature v4
  3. Use API key for subsequent authenticated requests

Data Loading Flow​

  1. Initial Page Load:

    • Load configuration from /app-first-page.json
    • Load schema from schema.villamarket.com
    • Load catalog tree from /api/v2/catalog-tree/catalog-tree
    • Load banners from /api/v2/catalog-tree/banner-tree and /api/v2/catalog-tree/sticky-banner
    • Load product list from /api/product/productlist/onlineData

  2. Inventory & Pricing:

    • Load inventory from /api/inventory2/{branchId}
    • Load prices from /api/price/getallgz or S3 bucket

  3. Product Images:

    • Load from /api/group/image/{groupId}/{imageId} or CloudFront CDN

Search Flow​

  1. User enters search query
  2. Call /api/search2/semantic_search?query={query}
  3. Display results with product images and details

Error Handling​

Most APIs follow standard HTTP status codes:

  • 200 OK: Successful request
  • 400 Bad Request: Invalid parameters
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server error

Rate Limiting​

Rate limiting may apply to certain endpoints. Check response headers for rate limit information:

  • X-RateLimit-Limit: Maximum requests per time window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when rate limit resets

CORS Policy​

APIs are configured to accept requests from shop.villamarket.com domain. Cross-origin requests may require proper CORS headers.

Notes​

  • Many endpoints use AWS Signature Version 4 for authentication
  • Image endpoints support various formats (.webp, .png, .jpg)
  • Price and inventory data may be cached; use timestamp parameters for cache busting
  • Some endpoints return compressed (gzip) data for performance
  • S3 buckets use signed URLs for secure access
  • Analytics endpoints are called asynchronously and don't affect page functionality