Use Places Aggregate API to create a custom location score

Objective

Finding the ideal location, whether a hotel for your upcoming vacation or a family-friendly apartment, often involves a frustrating and time-consuming process of comparing numerous options. What if you could help make this easier for your users by providing a customized metric that reveals a hotel's suitability for tourists or rank apartment listings based on their family friendliness, transforming a tedious chore into an effortless decision.

This document outlines how to use Places Aggregate API to generate dynamic, custom location scores, based on the density of places within a defined geographic area. The score, a numerical ranking against your specified criteria, will instantly communicate how suitable the location is for their needs.

Consider a scenario where you're promoting hotels in a city and want to highlight those in the most attractive tourist areas by creating a good for tourists score. Use Places Aggregate API to count how many relevant place types are near each hotel. For example, you know that your customers value hotels in locations that are nearby a number of the following:

• Restaurants & Coffee shops
• Parks & Museums
• Clothing stores

By applying importance weightings to the counts of these selected place types, you can calculate an overall score for each hotel location. The score reflects the overall suitability of the location, based on the nearby places. The weightings assigned to each place type should align with your specific use case and what's important to your target audience. This document will use a good for tourists score as the main example, but your score can be built to reflect your user demographics and needs.

Prerequisites

Before reading this document, familiarity with the following documentation is recommended:

• Places Aggregate API developer documentation to understand the technical details and the available parameters.
• [Optional] Gemini Developer API developer documentation to understand how to call Gemini using an API and is used in this document as an option to generate the custom location score.

Demo

This demo shows an example of the custom location score in action. Choose a city from the drop-down, and click the Calculate Custom Score button to display the custom location score for five pre-populated locations.

Select relevant place types

The first step to building your custom location score is to decide on the place types that are relevant to your customers from Table A. As we are creating a good for tourists score, we have selected the following place types that tourists will want to be located near during their stay:

• restaurant
• park
• clothing_store
• museum
• coffee_shop

Next, assign a weighting to each of these place types, reflecting its relative importance in the final score. The weightings should be determined based on what's most important for your use case and your user's preferences. For this example, the weighting scale will be between 0 and 1, as follows:

Call Places Aggregate API

Now that you have a list of place types you're interested in, the next step is to call Places Aggregate API.

Places Aggregate API requires a location filter. For this example use circle, with the center latLng being the location of your hotel, and a radius of 500m. Also set the ratingFilter to return places with a rating between 3.8 and 5, excluding lower rated places from the counts.

Experiment with varying the settings of the location filter for your specific use case. For example, you might want to capture places within a wider radius from your center latitude and longitude by increasing the value of radius. Alternatively, you might want to use a different method to set the search area, such as Region or Custom area.

Familiarize yourself with the location filter section of the Places Aggregate API documentation to learn about the options available to you.

Call Places Aggregate API for each place type and location you'd like to generate a custom score for. For example, call for the restaurant Place Type for one of your hotels:

curl --location 'https://areainsights.googleapis.com/v1:computeInsights' \
--header 'X-Goog-Api-Key: API_KEY \
--header 'Content-Type: application/json' \
--data '{
    "insights": [
        "INSIGHT_COUNT"
    ],
    "filter": {
        "locationFilter": {
            "circle": {
                "latLng": {
                    "latitude": 51.51611,
                    "longitude": -0.12726
                },
                "radius": 500
            }
        },
        "typeFilter": {
            "includedTypes": [
                "restaurant"
            ]
        },
        "ratingFilter": {
            "minRating": 3.8,
            "maxRating": 5
        }
    }
}'

After all calls to the API have been completed, you have data that looks like this for each location:

Generate the custom location score

Now you have the count of places and weighting for each place type for each location you can now generate the custom location score. We will discuss two options in this section, using a local algorithm, or using the Gemini Developer API.

Option 1: Use an algorithm

The first option we'll cover is using a local algorithm to generate a score using the weightings and counts for each Place Type. Normalize this score to a 0 to 5 scale, where higher values indicate a more attractive area based on your criteria. For this example, generate two JavaScript objects from the data above:

    {
      "restaurant": 56,
      "park": 3,
      "clothing_store": 32,
      "museum": 8,
      "coffee_shop": 41
    }
    

    {
      "restaurant": 0.8,
      "park": 0.6,
      "clothing_store": 0.3,
      "museum": 0.2,
      "coffee_shop": 0.5
    }
    

Generate a score from the counts and weightings by multiplying the itemCounts by the typeWeights, and adding the results to an overall weightedCount:

let weightedCount = 0;
for (const itemType in itemCounts) {
  weightedCount += itemCounts[itemType] * typeWeights[itemType];
}
weightedCount = weightedCount.toFixed(2);

For this example, the output of this step is: 78.3.

Now you can use logarithmic normalization to generate the final score for this location on a scale between 0 and 5:

if (weightedCount === 0) {
   normalizedScore = 0;
} else {
   normalizedScore = Math.log(weightedCount + 1);
}

// Clamp between 0 and 5
normalizedScore = Math.max(0, Math.min(5, normalizedScore));

For this example, the final score output is: 4.36 (rounded to two decimal places).

Option 2: Use Gemini Developer API

As an alternative to using a local algorithm, Gemini Developer API offers a powerful way to compute the custom location score for all locations. Simply provide the count and weighting data with system instructions for all your hotel locations.

This method is especially useful if you have nuanced information you'd like to include in the calculation, such as:

• Text descriptions for each hotel location, for example: "This location is suitable for families and the area is quiet at night".
• Information about your user, such as: "This user is booking for a family and prefers a quiet area in a central location".

The Gemini Developer API can understand and factor in this qualitative data leading to a more sophisticated and relevant score beyond a purely mathematical approach.

By using the Gemini Developer API, in addition to the place type and weighting table above, you can have description data for each location that looks like this:

These qualitative descriptions along with any user information or preferences can be included in your prompt to Gemini.

System instructions

Gemini requires instructions, along with the raw data, to know that it's expected to generate a score for each location, based on the data points provided. An example system instruction to achieve this could be as follows:

You will be given a json file containing details about a number of locations grouped by their latitude and longitudes.

Within the location details is information about the count of places nearby the location that match a specific category, and the weighting of importance of that category, between 0 - 1.

You will also be given information about the user's preference, and a description of each location. Take this into consideration when generating scores.

Generate a location suitability score taking these into account for each location. The score should be between 1 - 5 inclusive, to two decimal places. The minimum score a location can receive is 1.

Output in JSON

The above system instructions lets Gemini know what data to expect, and what the expected output from the AI model is. It also requests the output in JSON.

Structured output

While we have asked Gemini to output the result in JSON, we need to be more specific about the structure of the output, so we know what to expect when we query it with code. For this, we can add an additional structured output instruction to the request, using the responseSchema field in the Gemini API. This uses an OpenAPI schema object to constrain the model output.

For example:

{
  "type": "array",
  "description": "Array of location data with score",
  "items": {
    "type": "object",
    "properties": {
      "location": {
        "type": "object",
        "description": "Geographical coordinates of the location",
        "properties": {
          "latitude": {
            "type": "number",
            "format": "float",
            "description": "Latitude of the location"
          },
          "longitude": {
            "type": "number",
            "format": "float",
            "description": "Longitude of the location"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ]
      },
      "score": {
        "type": "string",
        "description": "A score associated with the location"
      }
    },
    "required": [
      "location",
      "score"
    ]
  }
}

This example requests that Gemini outputs a JavaScript array with the following:

• Location latitude & longitude
• The custom location score

Using the above system instructions and structured output, the response from Gemini for one location would look like this, with score being the custom location score:

[
  {
    "location": {
      "latitude": 51.51611,
      "longitude": -0.12726
    },
    "score": "4.13"
  }
]

Display the score

Once you have generated the custom location score for each location using one of the described methods, it can be displayed alongside the details of your hotel, or used as a search filtering option. For example, "show me places with a high good for tourists score". This will enable your customers to make data based decisions when booking.

Conclusion

Using custom locations scores can be a powerful tool to give your users an at a glance overview of the suitability of an area. This document demonstrated generating custom location scores for various locations using five separate place types. This implementation can be modified to suit your needs, and similar place types can be combined into one request, to return the aggregated count of those types, to provide to your custom location scoring solution.

Try Places Aggregate API today to generate insightful location scores to help your customers make well-informed location-based decisions!

Contributors

Henrik Valve | DevX Engineer