Localities JS API Guide

Installation, configuration, usage and examples for the Woosmap Localities JavaScript API to integrate location search and geocoding into your web applications.

Sample Usage
Quick Start Checklist
Main Concepts
Settings Overview
Troubleshooting & Best Practices
Resources

The Woosmap Localities JS API lets you integrate location search and geocoding into your web applications with flexible, programmatic control.

Sample Usage

This example shows how to use the Localities JS API for autocomplete and details retrieval.

            const customDescription =
  'postal_code:"{name} ({postal_town}) - {administrative_area_level_0}"';
let localitiesAutocompleteService;
let inputElement: HTMLInputElement;
let suggestionsList: HTMLUListElement;
let clearSearchBtn: HTMLButtonElement;
let responseElement: HTMLElement;

function init(): void {
  if (inputElement && suggestionsList) {
    inputElement.addEventListener("input", handleAutocomplete);
    inputElement.addEventListener("keydown", (event) => {
      if (event.key === "Enter") {
        const firstLi = suggestionsList.querySelector("li");
        if (firstLi) {
          firstLi.click();
        }
      }
    });
  }
  clearSearchBtn.addEventListener("click", () => {
    inputElement.value = "";
    suggestionsList.style.display = "none";
    clearSearchBtn.style.display = "none";
    responseElement.style.display = "none";
    inputElement.focus();
  });

  localitiesAutocompleteService =
    new window.woosmap.localities.AutocompleteService("YOUR_API_KEY");
}

function handleAutocomplete(): void {
  if (inputElement && suggestionsList) {
    const input = inputElement.value;
    input.replace('"', '\\"').replace(/^\s+|\s+$/g, "");
    if (input !== "") {
      localitiesAutocompleteService.autocomplete(
        { input, custom_description: customDescription },
        displaySuggestions,
        (errorCode: number, errorText: string) => {
          console.error(
            `Error autocomplete localities: ${errorCode}:${errorText}`,
          );
        },
        0,
      );
    } else {
      suggestionsList.style.display = "none";
      clearSearchBtn.style.display = "none";
    }
  }
}

function displaySuggestions({
  localities,
}: woosmap.map.localities.LocalitiesAutocompleteResponse) {
  if (inputElement && suggestionsList) {
    suggestionsList.innerHTML = "";
    if (localities.length > 0) {
      localities.forEach((locality) => {
        const li = document.createElement("li");
        li.innerHTML = formatPredictionList(locality) ?? "";
        li.addEventListener("click", () => {
          inputElement.value = locality.description ?? "";
          suggestionsList.style.display = "none";
          localitiesAutocompleteService.getDetails(
            locality.public_id,
            displayLocalitiesResponse,
          );
        });
        suggestionsList.appendChild(li);
      });
      suggestionsList.style.display = "block";
      clearSearchBtn.style.display = "block";
    } else {
      suggestionsList.style.display = "none";
    }
  }
}

function formatPredictionList(locality): string {
  const prediction = locality;
  const predictionClass = "no-viewpoint";
  const matched_substrings = prediction.matched_substrings;
  let formatted_name = "";
  if (
    prediction.matched_substrings &&
    prediction.matched_substrings.description
  ) {
    formatted_name = bold_matched_substring(
      prediction["description"],
      matched_substrings.description,
    );
  } else {
    formatted_name = prediction["description"];
  }

  let html = "";
  html += `<div class="prediction ${predictionClass}">${formatted_name}</div>`;

  return html;
}

function displayLocalitiesResponse(
  selectedLocality: woosmap.map.localities.LocalitiesPredictions,
) {
  if (responseElement) {
    responseElement.innerHTML = `<code>${JSON.stringify(selectedLocality, null, 2)}</code>`;
    responseElement.style.display = "block";
  }
}

function bold_matched_substring(string: string, matched_substrings: string[]) {
  matched_substrings = matched_substrings.reverse();
  for (const substring of matched_substrings) {
    const char = string.substring(
      substring["offset"],
      substring["offset"] + substring["length"],
    );
    string = `${string.substring(
      0,
      substring["offset"],
    )}<span class='bold'>${char}</span>${string.substring(
      substring["offset"] + substring["length"],
    )}`;
  }
  return string;
}

document.addEventListener("DOMContentLoaded", () => {
  inputElement = document.getElementById(
    "autocomplete-input",
  ) as HTMLInputElement;
  suggestionsList = document.getElementById(
    "suggestions-list",
  ) as HTMLUListElement;
  clearSearchBtn = document.getElementsByClassName(
    "clear-searchButton",
  )[0] as HTMLButtonElement;
  responseElement = document.getElementById(
    "response-container",
  ) as HTMLElement;
  init();
});

declare global {
  interface Window {
    // currently, the localities JS API typings are not exported, so we use `any` here
    woosmap: {
      localities: {
        AutocompleteService: new (key: string) => any;
      };
    };
  }
}

    

            const customDescription =
  'postal_code:"{name} ({postal_town}) - {administrative_area_level_0}"';
let localitiesAutocompleteService;
let inputElement;
let suggestionsList;
let clearSearchBtn;
let responseElement;

function init() {
  if (inputElement && suggestionsList) {
    inputElement.addEventListener("input", handleAutocomplete);
    inputElement.addEventListener("keydown", (event) => {
      if (event.key === "Enter") {
        const firstLi = suggestionsList.querySelector("li");

        if (firstLi) {
          firstLi.click();
        }
      }
    });
  }

  clearSearchBtn.addEventListener("click", () => {
    inputElement.value = "";
    suggestionsList.style.display = "none";
    clearSearchBtn.style.display = "none";
    responseElement.style.display = "none";
    inputElement.focus();
  });
  localitiesAutocompleteService =
    new window.woosmap.localities.AutocompleteService("YOUR_API_KEY");
}

function handleAutocomplete() {
  if (inputElement && suggestionsList) {
    const input = inputElement.value;

    input.replace('"', '\\"').replace(/^\s+|\s+$/g, "");
    if (input !== "") {
      localitiesAutocompleteService.autocomplete(
        { input, custom_description: customDescription },
        displaySuggestions,
        (errorCode, errorText) => {
          console.error(
            `Error autocomplete localities: ${errorCode}:${errorText}`,
          );
        },
        0,
      );
    } else {
      suggestionsList.style.display = "none";
      clearSearchBtn.style.display = "none";
    }
  }
}

function displaySuggestions({ localities }) {
  if (inputElement && suggestionsList) {
    suggestionsList.innerHTML = "";
    if (localities.length > 0) {
      localities.forEach((locality) => {
        const li = document.createElement("li");

        li.innerHTML = formatPredictionList(locality) ?? "";
        li.addEventListener("click", () => {
          inputElement.value = locality.description ?? "";
          suggestionsList.style.display = "none";
          localitiesAutocompleteService.getDetails(
            locality.public_id,
            displayLocalitiesResponse,
          );
        });
        suggestionsList.appendChild(li);
      });
      suggestionsList.style.display = "block";
      clearSearchBtn.style.display = "block";
    } else {
      suggestionsList.style.display = "none";
    }
  }
}

function formatPredictionList(locality) {
  const prediction = locality;
  const predictionClass = "no-viewpoint";
  const matched_substrings = prediction.matched_substrings;
  let formatted_name = "";

  if (
    prediction.matched_substrings &&
    prediction.matched_substrings.description
  ) {
    formatted_name = bold_matched_substring(
      prediction["description"],
      matched_substrings.description,
    );
  } else {
    formatted_name = prediction["description"];
  }

  let html = "";

  html += `<div class="prediction ${predictionClass}">${formatted_name}</div>`;
  return html;
}

function displayLocalitiesResponse(selectedLocality) {
  if (responseElement) {
    responseElement.innerHTML = `<code>${JSON.stringify(selectedLocality, null, 2)}</code>`;
    responseElement.style.display = "block";
  }
}

function bold_matched_substring(string, matched_substrings) {
  matched_substrings = matched_substrings.reverse();

  for (const substring of matched_substrings) {
    const char = string.substring(
      substring["offset"],
      substring["offset"] + substring["length"],
    );

    string = `${string.substring(0, substring["offset"])}<span class='bold'>${char}</span>${string.substring(substring["offset"] + substring["length"])}`;
  }
  return string;
}

document.addEventListener("DOMContentLoaded", () => {
  inputElement = document.getElementById("autocomplete-input");
  suggestionsList = document.getElementById("suggestions-list");
  clearSearchBtn = document.getElementsByClassName("clear-searchButton")[0];
  responseElement = document.getElementById("response-container");
  init();
});

    

            /*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
#map {
  height: 100%;
}

/*
 * Optional: Makes the sample page fill the window.
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
  font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, Noto Sans, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
}

#autocomplete-container {
  display: flex;
  position: absolute;
  top: 10px;
  left: 10px;
  z-index: 1;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2), 0 -1px 0px rgba(0, 0, 0, 0.02);
  background: #fff;
  border-radius: 12px;
  padding: 0 12px;
  max-width: 320px;
  width: 100%;
  height: 42px;
  border: none;
  box-sizing: border-box;
  align-items: center;
  cursor: text;
  font-size: 15px;
}

#autocomplete-container .search-icon, #autocomplete-container .clear-icon {
  color: inherit;
  flex-shrink: 0;
  height: 16px;
  width: 16px;
}

#autocomplete-container .clear-icon {
  transform: scale(1.3);
}

#autocomplete-input {
  box-sizing: border-box;
  padding: 0;
  height: 40px;
  line-height: 24px;
  vertical-align: top;
  transition-property: color;
  transition-duration: 0.3s;
  width: 100%;
  text-overflow: ellipsis;
  background: transparent;
  border-radius: 0;
  border: 0;
  margin: 0 8px;
  outline: 0;
  overflow: visible;
  appearance: textfield;
  font-size: 100%;
}

.clear-searchButton {
  display: none;
  height: 18px;
  width: 22px;
  background: none;
  border: none;
  vertical-align: middle;
  pointer-events: all;
  cursor: pointer;
}

#suggestions-list {
  border-radius: 12px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2), 0 -1px 0px rgba(0, 0, 0, 0.02);
  box-sizing: border-box;
  position: absolute;
  max-width: 320px;
  width: 100%;
  top: 100%;
  left: 0;
  z-index: 1;
  list-style: none;
  max-height: 80vh;
  margin: 5px 0 0;
  padding: 0;
  display: none;
  overflow-y: auto;
  background-color: #fff;
}

#suggestions-list.visible {
  display: block;
}

#suggestions-list li {
  padding: 12px;
  cursor: pointer;
  transition: background-color 0.3s ease;
}

#suggestions-list li:hover {
  background-color: #f2f2f2;
}

body {
  background-color: #eee;
  overflow: hidden;
}

#app {
  display: flex;
  flex-direction: column;
  overflow: hidden;
  height: 100vh;
  padding: 10px;
}

.search-container {
  position: relative;
  min-height: 45px;
}

.search-container #autocomplete-container {
  top: 0;
  left: 0;
}

pre {
  display: none;
  margin-top: 10px;
  margin-bottom: 20px;
  padding: 10px;
  border: 3px solid #c8c8c8;
  background-color: white;
  border-radius: 8px;
  overflow-y: auto;
  overflow-x: auto;
  font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier, monospace;
}

.bold {
  font-weight: 700;
}

.title {
  margin-block-end: 0;
  font-weight: 500;
}

.note {
  margin-block-start: 4px;
  font-size: 13px;
}


    

            <html>
  <head>
    <title>Localities JS API</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta charset="utf-8" />

    <script src="https://sdk.woosmap.com/localities/localities.2.0.js"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="app">
      <p class="title">Autocomplete input with Woosmap Localities JS API</p>
      <p class="note">
        <em
          >Custom Description for Postal Codes "{name} ({postal_town}) -
          {administrative_area_level_0}"</em
        >
      </p>
      <div class="search-container">
        <div id="autocomplete-container">
          <svg class="search-icon" viewBox="0 0 16 16">
            <path
              d="M3.617 7.083a4.338 4.338 0 1 1 8.676 0 4.338 4.338 0 0 1-8.676 0m4.338-5.838a5.838 5.838 0 1 0 2.162 11.262l2.278 2.279a1 1 0 0 0 1.415-1.414l-1.95-1.95A5.838 5.838 0 0 0 7.955 1.245"
              fill-rule="evenodd"
              clip-rule="evenodd"
            ></path>
          </svg>

          <input
            type="text"
            id="autocomplete-input"
            placeholder="Search a locality or a postal code..."
            autocomplete="off"
          />
          <button aria-label="Clear" class="clear-searchButton" type="button">
            <svg class="clear-icon" viewBox="0 0 24 24">
              <path
                d="M7.074 5.754a.933.933 0 1 0-1.32 1.317L10.693 12l-4.937 4.929a.931.931 0 1 0 1.319 1.317l4.938-4.93 4.937 4.93a.933.933 0 0 0 1.581-.662.93.93 0 0 0-.262-.655L13.331 12l4.937-4.929a.93.93 0 0 0-.663-1.578.93.93 0 0 0-.656.261l-4.938 4.93z"
              ></path>
            </svg>
          </button>
          <ul id="suggestions-list"></ul>
        </div>
      </div>
      <pre id="response-container"></pre>
    </div>
  </body>
</html>

    

Quick Start Checklist

Add the JS API script to your HTML:

        <script src="https://sdk.woosmap.com/localities/localities.2.0.js"></script>
<link rel="stylesheet" type="text/css" href="./style.css" />

Create the input and response elements:

        <input id="autocomplete-input" type="text" placeholder="Search a locality or a postal code..." />
<pre id="response-container"></pre>

Basic JS setup:

        const key = 'YOUR_API_KEY';
const autocompleteService = new woosmap.localities.AutocompleteService(key);
// Listen to input events and call autocompleteService.autocomplete()
// On selection, call autocompleteService.getDetails()

Add basic CSS for layout:

        #autocomplete-input { width: 100%; padding: 8px; font-size: 16px; }
#response-container { background: #f9f9f9; border: 1px solid #eee; padding: 12px; border-radius: 4px; margin-top: 12px; display: none; }

Main Concepts

Autocomplete: Listen to input events, call autocompleteService.autocomplete() to get suggestions.
Custom Description: Use the custom_description parameter to format suggestions (see sample for details).
Selection & Details: When a user selects a suggestion, call autocompleteService.getDetails() to fetch full details and display them.
UI Handling: Show/hide suggestions, clear input, and display results using basic DOM manipulation and CSS.
Accessibility & UX: Add keyboard support, clear button, and highlight matched substrings for a better experience.

For a complete working example, see the embedded sample and code tabs above.

Settings Overview

See the Localities JS API Reference for all available methods and options.
Use autocomplete() for suggestions and getDetails() for retrieving full details.
Configure parameters such as custom_description, types, components, and language for tailored results.

Troubleshooting & Best Practices

API Key Issues: Ensure your key is valid and domain restrictions are set in the Woosmap Console.
Minimum Input Length: Use a sensible minimum length (e.g. 3) to avoid unnecessary API calls.
Styling: Customize your input and results display with CSS for a better user experience.
Accessibility: Make sure your input is accessible (label, ARIA attributes).

Resources

‹ Store Locator Widget Mobile SDKs ›

Was this article helpful?

Have more questions? Submit a request