Introduction

Description

The WoosmapService is a specialized service layer responsible for interacting with the Woosmap Localities API. It provides location-based features such as:

• Autocomplete suggestions for cities, towns, and postal codes.
• Geolocation details including latitude and longitude for selected localities.

This service plays a critical role in:

• Enabling user-friendly address inputs.
• Supporting location-aware delivery and logistics flows.
• Enhancing search UX across e-commerce and mapping modules.

Purpose

• Acts as a client-side abstraction over the Woosmap Localities API.
• Provides location-based services like autocomplete suggestions and detailed locality data (latitude, longitude, etc.).
• Used primarily in address search, delivery coverage checks, and geo-based personalization.

Structure

• WoosmapService: Main service class that implements TWoosmapService interface.
• TWoosmapService: Defines the contract for autocomplete and detail fetch functionality.
• WoosmapError: Custom error class for handling Woosmap-specific errors.

Constructor

new WoosmapService(apiKey: string, baseApiUrl: string);

• apiKey: Required Woosmap public API key for authentication.
• baseApiUrl: Root URL of the Woosmap endpoint (e.g., https://api.woosmap.com).
• Initializes the service for use throughout the app.

const service = new WoosmapService("your_api_key", "https://api.woosmap.com");

Significance

• Checkout: To auto-suggest valid shipping addresses.
• User Profile: For setting or updating locations.
• Delivery Planner: For calculating distances or matching customers with depots.

Internal Utilities Used

• useAjaxServer: Used for server-side calls (autocomplete).
• useAjax: Used for client-side calls (details).
• Query parameters are passed directly to Woosmap endpoints using standard REST syntax.