Skip to content

NeighborhoodMatch (New)

Available in the US and Canada

NeighborhoodMatch displays a list of similar neighborhoods.

The affordability index (price comparison tag) is only available in the US


Screenshot of new NeighborhoodMatch SDK

Getting started


First, install the entry script with npm, yarn, or pnpm:

npm i --save @local-logic/sdks-js
yarn add @local-logic/sdks-js
pnpm add @local-logic/sdks-js

The script is also available in umd and es format from the Local Logic CDN:<VERSION>/index.<FORMAT>.js

<VERSION> is the latest script version number (which you can find on npm), and <FORMAT> is either umd or es.



Step 1: Instantiate an LLSDKsJS instance

Import LLSDKsJS and create a new localLogicSDK instance. If you installed LLSDKsJS using a script tag, you must access it from the window object.

import LLSDKsJS from "@local-logic/sdks-js";
const localLogicSDK = LLSDKsJS(
// Your API key or token

You can authenticate your SDK using an API key or OAuth token. The method you choose depends on your environment; if your page is using server-side rendering (SSR), the OAuth token may be preferrable. If you have a single-page application (SPA), you will likely want to use the API key since the CLIENT_SECRET needed to generate the OAuth token should never be exposed in a client-side environment.

If you authenticate using the token you need to prefix it with Bearer.

Step 2: Instantiate a SDK instance

Next, create an instance of the NeighborhoodMatch SDK. You must define a container element for it to render into.


// Define a container element
const container = document.createElement("div"); = `
height: 100%;
width: 100vw;
display: flex;
const neighborhoodLocation = {
lat: 37.8,
lng: -122.4,
localLogicSDK.create("neighborhood-match", container, {


As part of the NeighborhoodMatch SDK, you have the option to customize the implementation in three ways:

  1. Restrict the returned similar neighborhoods to only neighborhoods relevant to you.

    This is important because it allows you to keep the homeseeker in your funnel by not recommending neighborhoods outside of your territory or where you do not have a page. By default, when no configuration is provided “all” similar nearby neighborhoods are returned; the only filtering applied is to limit to other similar neighborhoods within the metropolitan statistical area (MSA) or within 100 kms, if the neighborhood is not within an MSA.

  2. Customize the images displayed for each neighborhood.

    This allows you to avoid prescribed images. By default, no images will be shown for neighborhoods without configured images.

  3. Assign each similar neighborhood card to a link.

    The vision here is that similar neighborhoods can be used to “shop” between neighborhoods by directly linking neighborhood pages (either NeighborhoodWrap implementations or even as an addition to non-NeighborhoodWrap neighborhood pages). The goal of recommending similar neighborhoods is to allow a user to click through and learn about the neighborhood and view homes in the area. For this to work, links must be assigned for when a user clicks on each card. By default, no link is added to cards without a link configured: they can be viewed but not clicked.

For the NeighborhoodMatch SDK, a configuration file is leveraged to customize the list of neighborhoods used and displayed to the user, to ensure they link within the implementing site’s available pages, and to customize the images displayed for each neighborhood.

When no configuration file is provided, no images will be shown for each neighborhood, the list of similar neighborhoods will not be filtered, and the cards in the SDK will not display as links. However, the SDK can still be implemented without the configuration being applied and it will be updated to match the given neighborhood once the configuration file is applied.

Generating a Neighborhood Match Configuration File

  1. Prepare a CSV file that contains the fields outlined below.
  2. Send the CSV to Local Logic via a support ticket. The team at Local Logic will help convert the neighborhoods to supported geog_id’s and apply the configuration the next business day.
CSV Information

Example configuration file - geog_id

Example configuration file - neighborhood name

geog_id OR neighborhoodtruegeog_id is the specific Local Logic external ID for the neighborhood, if available and known. neighborhood is the name of the neighborhood for identifying and matching to our Local Logic list of neighborhoods.
thumbnail_urltrueThe full URL for the image representing the neighborhood when it appears in configured NeighborhoodMatch SDKs.
redirect_urltrueThe full URL that should be the source link if a user clicks on the neighborhood. It should be a URL on your site that exists (or will exist) for each neighborhood.
The "neighborhood" option can be used if the Local Logic geog_id is unknown for the desired neighborhood. In this case, be as descriptive as possible: “Little Italy, San Diego, CA” is better than “Little Italy,” as there are at least 8 Little Italies in the United States.
For the "thumbnail_url", the server where the image thumbnail URL is hosted needs at a minimum to have the following addresses added as allowed origins to the CORS header:
  • Required for the SDK implementation:

  • Highly recommended for support, testing, and debugging: http://localhost:3000 http://localhost:3001

The thumbnail image could also be publicly accessible (if CORS headers are not used).

It’s recommended that your thumbnail image(s) be at minimum 144 px by 400 px and at maximum 500 px by 800 px for best results in the SDK.

Screenshot of new NeighborhoodMatch SDK Configuration

React applications

The SDKs are designed to work with React and other declarative frameworks.


import { useRef, useEffect } from "react";
import LLSDKsJS from "@local-logic/sdks-js";
const localLogicSDK = LLSDKsJS(<API_KEY>);
function LocalNeihborhoodMatch() {
const containerRef = useRef(null);
useEffect(() => {
if (!containerRef.current) {
const myLocation = {
lat: 45.5282164,
lng: -73.5978527,
const neighborhoodMatch = localLogicSDK.create(
containerRef.current, {
// It is important to destroy the instance when the component is unmounted.
return () => {
}, []);
return (
height: "100%",
width: "100vw",
export default LocalNeihborhoodMatch;

Vanilla Javascript


<!DOCTYPE html>
<title>NeighborhoodWrap Page Javascript Example</title>
<meta charset="UTF-8" />
#widgetMap {
height: 100%;
width: 100%;
<div id="neighborhoodMatchContainer"></div>
function neighborhoodMatch() {
(async () => {
// Your API key or token
const ll = LLSDKsJS("<API_KEY>", {
locale: "en", // Change to either english or french
const container = document.createElement("div");
container.setAttribute("id", "LocalNeihborhoodMatch");
// Set the styles of the container
// The widget needs to have an adaptable height because it expands to fit the content = `
height: 100%;
width: 100%;
display: flex;
// This is the div that will contain the widget
// Set the lat and lng of the location
const LAT = 45.528126;
const LNG = -73.598104;
const localMatch = ll.create("neighborhood-match", container, {
lat: LAT,
lng: LNG,


For more information on the different functions available with the SDK, please view our NPM packages documentation.


The update method is used to update the widget with new values. This can be useful when, for example, you want to change the widget location.


lat: 43.686941,
lng: -79.463814,

Browser support

The SDKs are configured with to support these browsers.


The SDKs are designed to receive most new changes (non-breaking features and bug fixes) without the need for a developer to manually update the script.


Local Logic SDKs JS comes packaged with TypeScript declarations.


Q: How do I change the language of the SDK?

A: You can change the language by specifying locale in the LLSDKsJS options. The supported options are "en" and "fr".

const ll = LocalLogicSDK(
// Your API key or token
locale: "fr",
© Local Logic 2024