Our JavaScript SDK provides an easy-to-use way to integrate Maps Untold into your product. You can use it to offer personalized recommendations based on a location such a a hotel or restaurant.

The SDK is initialized using MapsUntold.Init(). Channel object references to a certain channel such as a hotel or app that uses the recommended engine. Your organization can have multiple channels.


Setup

Follow these steps to integrate the Maps Untold JavaScript SDK into your app:

Install the SDK

Start by running npm install @mapsuntold/sdk in your project folder.

npm install @mapsuntold/sdk

Obtain Access Credentials

Before starting you need:

  • An API Token

  • A Channel slug


Usage

To get familiar with the Maps Untold SDK and API, go through the examples below.

Creating a channel instance

A channel can be thought of as a distribution point of the Maps Untold guide, adapted to your preferences. Initializing a channel requires an API key and a slug that identifies your channel.

import { MapsUntold } from "@mapsuntold/sdk";

const channel = await MapsUntold({
   apiKey: "YOUR_TOKEN",
   channelSlug: "YOUR_CHANNEL_SLUG"
});

A channel contains a name, a slug, a style object, example_locations and a default_location. In the case of the channel for a hotel, for example, the default_location is the hotel itself.


Retrieving categories

Maps Untold recommendations are filtered by parent category. A parent category is an entity that groups more specific categories together into general groups. The Restaurant parent category, for example, contains lunchrooms, bistros and specific kitchens (think Spanish, Greek, Korean, etc.). These categories may change over time. The list of parent categories can be retrieved in the following way:

const categories = await channel.getParentCategories();

The result looks like the output below. The id is the unique identifier of this category, that can be used to get recommendations within a certain category. The name field is the name of the category, while name_singular and name_plural can be used inside sentences that include the category. The icon field contains a URL to the icon that identifies the category.

[
    {
        "id": 1,
        "name": "Restaurants that feel like home",
        "name_singular": "restaurant",
        "name_plural": "restaurants that feel like home",
        "icon": "https://storage.mapsuntold.io/mu-public/icon/restaurant.svg",
         ...
    },
    ...
]

Retrieving channel recommendations

Recommendations can be retrieved in multiple ways. Non-personalized results based on the default location of the channel can be retrieved in the following way:

const recommendations = await channel.getRecommendations(categories[0].id);

The output contains a paginated list of locations, sorted by match score. The match score is calculated based on its similarity to the default location of the channel, or to a location specified by the user in case of personalized recommendations. See the example below:

{
   "count": 10,
   "next": null,
   "previous": null,
   "results": [
      {
         "match": 0.92,
         "location": {
            "id": 36200,
            "title": "ZIZO Restaurant Lounge Eindhoven",
            "description": "ZIZO Restaurant Lounge in Eindhoven biedt een ...",
            "phone": "...",
            "website": "...",
            "open_now": false,
            "open_today": false,
            "reviews_stars": 4.5,
            "reviews_count": 34,
            "category": {
               "id": 9,
               "name": "Restaurant"
            },
            "parent_category": {
               "id": 1,
               "name": "Restaurants that feel like home"
            },
            "address": {
               "country": "NL",
               "city": "Eindhoven",
               "postal_code": "5612 CD",
               "street": "Kruisstraat 63",
               "latitude": 51.4473563,
               "longitude": 5.4752259,
               ...
            },
            "media": [
               {
                  "thumbnail_url": "...",
                  "media_url": "...",
                  "type": "image"
               }
            ],
            "actions": [
               {
                  "text": "Directions",
                  "url": "https://www.google.com/maps/dir/?api=1&destination=ZIZO+Restaurant+Lounge+Eindhoven&destination_place_id=ChIJQ8UjrxnZxkcRmh3tLPb7tqk",
                  "icon": "directions"
               }
            ],
            ...
         },
         "distance": "700 m",
         ...
      },
      ...
   ]
}

Methods


getRecommendations(parentCategoryId: number , inputLocationId : number)

getRecommendations() allows you to get recommendations in a certain parent category for a specific location, which you can get id from via getLocationByPlaceId() or getLocationAutocomplete().

  • parentCategoryId: The ID of the parent category (e.g., 1)
  • inputLocationId: The Maps Untold location ID (e.g., 226)

getRecommendation(parentCategoryId: number , inputLocationId: number, locationId: number)

getRecommendation() allows you to get the recommendation match score and distance for a specific location, based on its similarity to the inputLocation.

  • parentCategoryId: The ID of the parent category (e.g., 1)
  • inputLocationId: The Maps Untold location ID (e.g., 226)
  • locationId: The Maps Untold location ID (e.g., 226)

getLocation(locationId: string)

Retrieves a location by its unique Maps Untold ID.

  • locationId: A string representing the unique Maps Untold location ID (e.g., "226").

getLocationAutocomplete(search: string)

Returns a list of locations based on a search term. Each result includes an ID, which can be used with getRecommendations() to get recommendations.

  • search: A string search term to find matching locations.

getLocationAutocompleteByCategory(search: string, parentCategoryId: number)

Returns a list of locations based on a search term. Each result includes an ID, which can be used with getRecommendations() to get recommendations.

  • search: A string search term to find matching locations.
  • parentCategoryId: The id of the parent category of the results.

getLocationByPlaceId(placeId: string)

Finds a location using a Google Place ID. The returned location ID can then be used with getRecommendations().

  • placeId: A Google Place ID (e.g., ChIJLQxiKzGu_wQRFWEYV6Zkusc).

getParentCategories()

Returns all parent categories assigned to your channel.


getParentCategory(parentCategoryId: number)

getParentCategory() provides recommendations based on your channel for a specif parent category. For example, restaurants based on your hotel guest profile.

  • parentCategoryId: The ID of the parent category (e.g., 1).

Need help or more advanced use cases? Reach out at gaby@mapsuntold.nl.