Events Calendar Pro offers the ability to perform smart location-based searches when filtering calendar events. This article aims to provide insight into how location search works in the background through the Google Maps API. If you’re interested in how to use location search, then head over to this article.

This requires Events Calendar Pro to be installed with a custom, unrestricted Google Maps API key, or better, a set of restricted API keys, which were set up based on our Creating Google Maps API Key Restrictions article.

How does the search happen?

When you are on a calendar page, you have a dedicated field for location search, as seen in this screenshot.

When you enter a phrase and click on Find Events, a request is sent to the Google Maps API in the background, which looks like this:

https://maps.googleapis.com/maps/api/geocode/json?address=search-term&key=AIza-enter-your-API-key-here

The search-term will be the phrase you typed in the “In a location” field, and the key will be your custom Google Maps API key.

The API will try to find a result and return that to the site.

You can run a request URL like the above in your browser – substituting the search term and the key with yours – and see the results the API sends back.

The site will then take the latitude and longitude coordinates that come with the result and will run a search within the existing venues (with saved latitude and longitude coordinates) using the search radius you set up under Events → Settings → Display tab → Map view search distance limit.

Then, it will give you the results found in your database and show the events happening at those venues on the front end.

It can happen that you don’t get any results though, despite having venues in the search radius. Let’s look at the different request scenarios.

Results of the API request

The provided API key is invalid

The error message speaks for itself: the key is an invalid one.

Solution: check if you have copied and pasted your API key correctly.

This API key is not authorized …

There can be some variations to this message depending on the exact issue.

  • This API key is not authorized to use this service or API.
  • This IP, site, or mobile application is not authorized to use this API key. Request received from IP address xxx.xxx.xxx.xxx, with empty referer

The reasons can be:

  • If you have set up your custom API key, then the Geocoding API has not been enabled for this API key.
    Solution: go to Google Cloud Console and ensure you have the Geocoding API enabled for the API key.
  • The API key used for Geocoding is restricted, and the request comes from a website, application, or IP address that is not on the allowed list.
    Solution: Check the IP address restrictions for the Geocoding API key. Please also check our related article on how to set up restrictions for your API keys correctly.

Note: When someone runs a search on your website, the request to the Google Maps API will go from the IP address of the server where your website is hosted. When you are running requests via a URL in your browser, the request goes from the IP address of your device.

API keys with referer restrictions cannot be used with this API

The restrictions for the Geocoding API key are not set up correctly.

Solution: Check the IP address restrictions for the Geocoding API key. Please also check our related article on how to set up restrictions for your API keys correctly.

Zero results

There are two main reasons for getting a response with zero results.

The API didn’t find any matches for the search phrase.

Or the API found too many results for the search phrase.

A good example of this would be searching for “Springfield,” a common and popular name for municipalities in various states in the US. Also, there are more than a handful of results for it in Europe in the form of cities and different retail stores.

So, even if you have multiple venues in Springfield on your site, the location search will not return any results because the Google Maps API could not return an unambiguous result.

Solution: provide more details in the search.

(Some tweaks might work; check them out below.)

Wrong result

Let’s imagine I live in a town called Crieff in the UK. I want to go out on Friday night, but there’s nothing happening here, so I search for the nearest bigger town with some action: Perth. So I type “Perth” in the location search box and get results for… Australia.

Obviously, Perth, Australia, is a bigger place than Perth, UK, and likely more popular, too, so likely that is why that comes up as a result. But that will not show anything on the calendar I can use.

Again, the solution is to provide more details in the search term and search for “Perth, UK.” Alternatively, using some tweaks.

Multiple results

In this example, we use the popular city of Springfield again and try to narrow the search. The search phrase “Springfield, US” already gives us a smaller set of results, three cities in this case, with three different latitude and longitude coordinates.

This, however, is still not good. How are we – or The Events Calendar – supposed to know where to search exactly?

Just like before, your site will not be able to show you any results. Location search is geared towards a single location and the search radius around that.

Solution: Providing more details in the search can help here, too.

One result

We go one step further and add the state to our search term: we’re looking for “Springfield, IL.” This is already specific enough for the Google Maps API, and it returns only one result. This is where the location search on the calendar can succeed.

The site takes the coordinates, and with the help of a sophisticated algorithm, it will run a search within the set search radius.

Once we have the venues, we can look up the events happening at those in the given timeframe, and we can show them on the selected calendar view.

Conclusion

As you can see from the above, when doing a location search, you will only get results in the calendar if the Google Maps API can return one, and only one answer, as the result.

The Google Maps API powers the location search, and it’s worth noting that we don’t have any influence over how the API itself works. We could say that the Google Maps API is a picky tool. In the end, it is “only” a machine which tries to do the best it can with the given data. It cannot guess what the user thinks. At least not yet.

The only influence we have is the search term that is sent to the API. While we cannot tell users how exactly to search to get the intended results, we do have the possibility to alter the search term based on our needs slightly.

Tweaks

Instruct users

Add a tooltip

If you have tested your location search and you found an approach that works, you can share it with your visitors as a tip. For example, you can add a short sentence below the search bar with this snippet.

<?php
add_action( 
	'tribe_template_after_include:events/v2/components/events-bar', 
	function( $file, $name, $template ) {
		echo '<div style="margin-top: -32px; margin-bottom: 32px; text-align:center; width: 100%; font-style: italic;">';
		echo 'When searching for a location, add the state after the city name. E.g. Springfield, MI.';
		echo '</div>';
	}, 
	10, 
	3 
);

This is how that would look like on the front end:

Check out our article about best practices Using Custom Code Snippets, and the one about Template Hooks. You might also find the article Using Template Filters and Actions helpful.

Change the placeholder text

You can change the “In a location” placeholder text with a template override.

  1. Take this file: wp-content/plugins/events-calendar-pro/src/views/v2/location/form-field.php
  2. Make a copy of it here: wp-content/themes/[your-theme]/tribe/events-pro/v2/location/form-field.php
  3. Adjust line 29, where you can find the placeholder string.

This is the result:

If you’re using the calendar in a language other than English, then you can change the placeholder text through translations. (And actually, you can do that in English as well.)

Localize your Google Maps

By default, Google Maps sets the locale to US-based locations. Fortunately, it is easy to change that and can help in certain scenarios. (For example, the one with Perth, UK.) Please refer to the article Change the Google Maps Localization Option for details.

Tweak the search phrase

We cannot expect the customers to know how to get the best results with location search. But we can aid them with a little tweak. This can be useful if all your venues are in the same state, country, or area.

This snippet will add a predefined string – “TX” – after the search phrase before it is sent to the Google Maps API. So, when someone types in “Atlanta,” the search phrase will be tweaked, and “Atlanta, TX” will be sent to the API.

<?php
add_filter( 'tec_google_map_args', 'tec_limit_search_to_texas' );

function tec_limit_search_to_texas( $args ) {
	$args['address'] = $args['address'] . ", TX";
	return $args;
}
TAGS:
Notify us of out of date information