How to use Twilio Locality search from the API

I'm searching Available Phone Numbers using the Twilio API. Normally I use nearNumber to find numbers geographically near an existing phone number, but sometimes geo data isn't available, so I want to fallback to a City search.

From the Twilio web page I can type in a city, "Santa Clara", and get results in or near Santa Clara. But from the API this returns no results.

numbers = await this.client.availablePhoneNumbers('US').local.list({
        inLocality: 'Santa Clara',
        smsEnabled: true,
        voiceEnabled: true,
      });

In the past I thought I should use a City, State syntax, but that also returned nothing.

How do I use the inLocality filter?

Docs: https://www.twilio.com/docs/phone-numbers/api/availablephonenumberlocal-resource Description of InLocality parameter:

Limit results to a particular locality or city. Given a phone number, search within the same Locality as that number.

Solution

While not made clear in any way in the documentation, through testing I found that inLocality when used with a City name is a sub-filter, and should include the state name in inRegion.

numbers = await this.client.availablePhoneNumbers('US').local.list({
        inLocality: 'Santa Clara',
        inRegion: 'CA',
        smsEnabled: true,
        voiceEnabled: true,
      });

When the City/State are provided, in separate fields, then it works.

Special Cases

During testing I found that some locations are stored only with the Locality information. For example, searching for Locality: "Chicago", Region: "IL" returns nothing. But if you remove the Region and only search for "Chicago" you get results. Reviewing these results shows that they don't have a Region specified.

So I wrote my code to try it with a City, State pair, and if that returns nothing to try it without the State.