Improve address autocomplete: Augment Google suggestions with DB-stored addresses

[paulo-rossy]

Hello team!

I'm experiencing an issue with the address service that uses the Google provider.
Expected behavior:
When entering a street name (e.g., Lagos de coronas), the service should return multiple houses from that street, including the street itself.

Problem with Google API:
Autocomplete requires users to start typing numbers (house numbers) and returns only up to 5 exact addresses.
Relevant references:

• StackOverflow: Autocomplete house number
• StackOverflow: Not returning street numbers
• Google Documentation

Test queries:

1. With types:

   https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Lagos%20de%20Coronas&key=[]&types=street_address  
   

2. Without types (default):

   https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Lagos%20de%20Coronas&key=[]  
   

---

Proposed solution:
For every item from suggest, search the DB for string matches and augment the results.

Example:

Query: Lagos de coronas
Google’s response:

• Lagos de coronas, Zaragoza
• Lagos de coronas, Madrid

After DB search:

• Lagos de coronas, Zaragoza (from Google)
  • Lagos de coronas, Zaragoza 1 (from DB)
  • Lagos de coronas, Zaragoza 2 (from DB)
  • Lagos de coronas, Zaragoza 3 (from DB)
• Lagos de coronas, Madrid (from Google)
  • Lagos de coronas, Madrid 1 (from DB)
  • Lagos de coronas, Madrid 2 (from DB)

---

DB search challenge:

• address_contains is slow and imprecise.
• start_with/end_with are faster, but data in the Address schema is normalized (e.g., C. de los Lagos de Coronas, 23, 50011 Zaragoza, España), making it incompatible with direct searches for "Lagos de coronas".

Proposed fix:
Use address_source with sources formatted as: country, region, street, house.
Modifications needed for searchByGooglePlaceId:

• Currently, address_source uses a googleplaceid prefix, which prevents effective searches.
• Additional address_source entries must be saved in a start_with-compatible format.

Pseudocode for GoogleSuggestionProvider.js:

  for (const suggestion of suggestions) {
    const existedAddressSources = await AddressSource.getAll(context, {
      source_starts_with: 'transformed suggestion to search',
    })

    if (existedAddressSources.length > 0) {
      for (const existedSource of existedAddressSources) {
        const existedAddress = await Address.getOne(context, { id: existedSource.address })
        // index of suggestion, insert into suggestions
      }
    }
  }

  return suggestions

---

Questions:

1. Thoughts on implementation approach?
2. Will the team handle this or should I fix it?
3. Recommendations for functions/implementation?

Thank you for your time!

[paulo-rossy]

Real-World Example:
User enters:
España, Zaragoza, Calle de los Lagos de Coronas

Current Response from Google Suggest Provider:
Returns only the street:

[
  {
    "value": "España, Zaragoza, Calle de los Lagos de Coronas",
    "unrestricted_value": "Calle de los Lagos de Coronas, Zaragoza, España",
    "rawValue": "googlePlaceId:EjBDYWxsZSBkZSBsb3MgTGFnb3MgZGUgQ29yb25hcywgWmFyYWdvemEsIEVzcGHDsWEiLiosChQKEgl1R1ZlEmtZDREmXAKluJETzRIUChIJkY5hXt0UWQ0RqImEFfET30k",
    "data": {

    },
    "provider": {
      "name": "google",
      "rawData": {
        "description": "Calle de los Lagos de Coronas, Zaragoza, España",
        "matched_substrings": [
          {
            "length": 16,
            "offset": 13
          }
        ],
        "place_id": "EjBDYWxsZSBkZSBsb3MgTGFnb3MgZGUgQ29yb25hcywgWmFyYWdvemEsIEVzcGHDsWEiLiosChQKEgl1R1ZlEmtZDREmXAKluJETzRIUChIJkY5hXt0UWQ0RqImEFfET30k",
        "reference": "EjBDYWxsZSBkZSBsb3MgTGFnb3MgZGUgQ29yb25hcywgWmFyYWdvemEsIEVzcGHDsWEiLiosChQKEgl1R1ZlEmtZDREmXAKluJETzRIUChIJkY5hXt0UWQ0RqImEFfET30k",
        "structured_formatting": {
          "main_text": "Calle de los Lagos de Coronas",
          "main_text_matched_substrings": [
            {
              "length": 16,
              "offset": 13
            }
          ],
          "secondary_text": "Zaragoza, España"
        },
        "terms": [
          {
            "offset": 0,
            "value": "Calle de los Lagos de Coronas"
          },
          {
            "offset": 31,
            "value": "Zaragoza"
          },
          {
            "offset": 41,
            "value": "España"
          }
        ],
        "types": [
          "geocode",
          "route"
        ]
      }
    },
    "type": null
  }
]

User Expectation:
The system should additionally return house numbers from the DB, for example:

• Calle de los Lagos de Coronas, 12
• Calle de los Lagos de Coronas, 24
• Calle de los Lagos de Coronas, 37

Endpoint
/suggest?s=lagos%20de%20coronas

[AleX83Xpert]

Hi @paulo-rossy!

First, let me clarify how the address service is designed.

The SuggestionKeystoneApp is just a "proxy" in front of an external provider. The main aim of this app is to give the user some options containing normalized strings (value, rawValue). When the user selects one option, the normalized string will be passed to the SearchKeystoneApp.

The SearchKeystoneApp is more complex than the app for suggestions. It has some logic before returning the searched normalized result. The main part of the searchApp is plugins. The plugin defines where to search for the data using user input. For example, the first plugin is SearchByAddressKey; if it finds nothing, the SearchBySource plugin works, and so on. These plugins use the local database for searching. It is useful to reduce the costs. The local database works as a cache before external paid providers. So, to improve local searching by not formalized strings (the address itself), we need to pass to the SearchKeystoneApp as normalized a string as possible. This is the reason why we use the suggestion provider first. Users may type different strings, but they will be normalized by the suggestion provider. The string passed to the search app becomes the source for the found address.

You may find the plugins queue at the bottom of the index.js file. Some plugins work only for formalized strings (SearchByAddressKey, SearchByGooglePlaceId), see the AbstractSearchPlugin.isEnabled function.
When Google is used as the external provider, we decided to pass the Google place ID between the suggestions provider and the search provider. This guarantees that we pass to the search app the same string, regardless of what the user typed.

Now, answering your questions:

1. Use normalized strings instead of "googlePlaceId:..." is normal. We use this approach for the Dadata provider.
2. You may feel free to modify the logic within the google suggestion/search apps. For example, use the human-readable address returned from the suggestion provider instead of google place id (rawValue=value). Or call the local database or the Google API while creating the suggestions array for the user.
3. If you decide to make additional calls to the Google API, please consider using sessions to decrease costs.

Also, I've found that we use legacy API. If you have some time, you may use the new API. Here is some info for migrating. And here is the Node.js package for Google Places API.

[pahaz]

Yes, you can do that. As I understand, you want to improve accuracy for suggestions.

• When adding an address via search, save an extra AddressSource to enrich future lookups.
• On suggest use the stored address source data to refine/improve suggestions.
• To avoid extra load, apply this only to the top 3 suggest items.