{"id":1896653,"date":"2019-10-18T13:19:46","date_gmt":"2019-10-18T17:19:46","guid":{"rendered":"https:\/\/theeventscalendar.com\/knowledgebase\/events-calendar-pro-location-search-2\/"},"modified":"2026-04-23T15:05:46","modified_gmt":"2026-04-23T19:05:46","slug":"calendar-location-search","status":"publish","type":"post","link":"https:\/\/theeventscalendar.com\/knowledgebase\/calendar-location-search\/","title":{"rendered":"Using The Events Calendar Location Search"},"content":{"rendered":"\n<iframe loading=\"lazy\" width=\"560\" height=\"315\" src=\"https:\/\/www.youtube.com\/embed\/7Oj5hDMu_Xk?si=Pe3pkRtLpPxnB26N\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" referrerpolicy=\"strict-origin-when-cross-origin\" allowfullscreen><\/iframe>\n\n\n\n<p>Events Calendar Pro includes location-based search, allowing visitors to filter calendar events by proximity to a city, address, or other mappable location. This article covers how to use the feature, how it works under the hood, and how to customize or troubleshoot it.<\/p>\n\n\n\n<p>\ud83d\udca1 Location search requires Events Calendar Pro and a Google Maps API key. Before proceeding, see <a href=\"https:\/\/theeventscalendar.com\/knowledgebase\/k\/setting-up-your-google-maps-api-key\/\">Setting Up Your Google Maps API Key<\/a>. For best results, set up <a href=\"https:\/\/theeventscalendar.com\/knowledgebase\/using-google-maps-api-key-restrictions\/\">restricted API keys<\/a> as described in that article.<\/p>\n\n\n\n<p>\ud83d\udca1 By default, only one venue will be visible on the map if you are using the built-in API key. To display more venues, you need a custom API key.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"h-using-location-search\">Using Location Search<\/h2>\n\n\n\n<p>When viewing your calendar with Events Calendar Pro active, an <strong>In a location<\/strong> field appears in the events search bar alongside the keyword and date fields.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2021\/06\/Screen-Shot-2021-06-11-at-1.41.55-PM.png\" alt=\"The events search bar showing the In a location field added by Events Calendar Pro\"\/><\/figure>\n\n\n\n<p>Enter an address, city, or other mappable location and click <strong>Find Events<\/strong>. The calendar and event listings will refresh to show events at venues within the search radius.<\/p>\n\n\n\n<p>In Map View, events are plotted on the map based on their venue&#8217;s location. After a location search, the map zooms to the relevant area and shows only nearby events.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2021\/06\/Screen-Shot-2021-06-11-at-1.44.11-PM.png\" alt=\"Map View showing all events plotted by venue location before a location search\"\/><\/figure>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2021\/06\/Screen-Shot-2021-06-11-at-1.47.31-PM.png\" alt=\"Map View after a location search showing only nearby events\"\/><\/figure>\n\n\n\n<p>Location search works on all calendar views \u2014 List, Month, Day, Week, Map, and Photo \u2014 and pairs well with the <a href=\"https:\/\/theeventscalendar.com\/product\/wordpress-events-filterbar\/\">Filter Bar<\/a> add-on. When Filter Bar is active alongside Events Calendar Pro, a <strong>Distance<\/strong> filter lets users adjust the search radius.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2021\/06\/Screen-Shot-2021-06-11-at-1.50.19-PM.png\" alt=\"The Distance filter in the Filter Bar sidebar, allowing users to adjust the location search radius\"\/><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"h-hiding-the-location-search-field\">Hiding the Location Search Field<\/h3>\n\n\n\n<p>By default, the location search field appears on all calendar views. To restrict it to map-based views only, go to <strong>Events \u2192 Settings \u2192 Display<\/strong> and enable <strong>Hide location search<\/strong> under the Calendar Display heading.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2021\/06\/Screen-Shot-2021-06-11-at-1.51.42-PM.png\" alt=\"The Hide location search checkbox in Events Settings Display tab\"\/><\/figure>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2021\/06\/Screen-Shot-2021-06-11-at-1.52.56-PM.png\" alt=\"The events search bar after location search is hidden, showing only keyword and date fields\"\/><\/figure>\n\n\n\n<p>\ud83d\udca1 This setting only appears when a custom API key is configured.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"h-filtering-events-by-location-in-wp-query\">Filtering Events by Location in WP_Query<\/h3>\n\n\n\n<p>From Events Calendar Pro version 4.4.16, the arguments <code>tribe_geoloc<\/code>, <code>tribe_geoloc_lat<\/code>, and <code>tribe_geoloc_lng<\/code> are available for use in <a href=\"https:\/\/theeventscalendar.com\/knowledgebase\/k\/crafting-custom-event-queries\/\">WP_Query<\/a> and <a href=\"https:\/\/theeventscalendar.com\/knowledgebase\/k\/using-tribe_get_events\/\">tribe_get_events()<\/a> to filter events by location programmatically.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"h-how-location-search-works\">How Location Search Works<\/h2>\n\n\n\n<p>Understanding the mechanics behind location search helps explain why some searches return no results, and what you can do about it.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"h-the-search-process\">The Search Process<\/h3>\n\n\n\n<p>When a user enters a location and clicks Find Events, the site sends a geocoding request to the Google Maps API:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: plain; title: ; notranslate\" title=\"\">\nhttps:\/\/maps.googleapis.com\/maps\/api\/geocode\/json?address=search-term&amp;amp;key=YOUR-API-KEY\n<\/pre><\/div>\n\n\n<p>The API returns latitude and longitude coordinates for the search term. The site then searches its database of saved venues \u2014 those with stored latitude and longitude \u2014 within the radius you&#8217;ve set under <strong>Events \u2192 Settings \u2192 Display \u2192 Map view search distance limit<\/strong>.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/s-d-l.png\" alt=\"The Map view search distance limit setting in the Events Settings Display tab\"\/><\/figure>\n\n\n\n<p>Events at matching venues within the timeframe are then shown in the selected calendar view. Location search only succeeds when the Google Maps API returns exactly one result \u2014 neither zero nor multiple.<\/p>\n\n\n\n<p>\ud83d\udca1 You can test a geocoding request by pasting the URL above into your browser (substituting your search term and API key) to see what the API returns.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"h-api-response-scenarios\">API Response Scenarios<\/h3>\n\n\n\n<h4 class=\"wp-block-heading\" id=\"h-invalid-api-key\">Invalid API Key<\/h4>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/ecp_location_search_key_invalid.jpg\" alt=\"Error message showing the API key is invalid\"\/><\/figure>\n\n\n\n<p>The key was not copied correctly. Check and re-enter your API key under <strong>Events \u2192 Settings \u2192 Integrations<\/strong>.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\" id=\"h-api-key-not-authorized\">API Key Not Authorized<\/h4>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/ecp_location_search_key_not_authorized.jpg\" alt=\"Error message showing the API key is not authorized for this service\"\/><\/figure>\n\n\n\n<p>This can mean one of the following:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>You&#8217;re using the default built-in API key, which doesn&#8217;t support location search. <a href=\"https:\/\/theeventscalendar.com\/knowledgebase\/setting-up-your-google-maps-api-key\/\">Set up a custom API key.<\/a><\/li>\n\n\n\n<li>The Geocoding API hasn&#8217;t been enabled for your API key. Go to <a href=\"https:\/\/console.cloud.google.com\/google\/maps-apis\/api-list\">Google Cloud Console<\/a> and enable it.<\/li>\n\n\n\n<li>The API key has IP or domain restrictions that exclude the server&#8217;s IP address. Geocoding requests originate from your server&#8217;s IP, not the visitor&#8217;s browser. Check your restriction settings.<\/li>\n<\/ul>\n\n\n\n<h4 class=\"wp-block-heading\" id=\"h-api-keys-with-referer-restrictions-cannot-be-used\">API Keys with Referer Restrictions Cannot Be Used<\/h4>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/ecp_location_search_key_restricted.jpg\" alt=\"Error message about referer restrictions on the API key\"\/><\/figure>\n\n\n\n<p>The Geocoding API key has HTTP referer restrictions instead of IP restrictions. See <a href=\"https:\/\/theeventscalendar.com\/extensions\/google-maps-api-key-restrictions\/\">Creating Google Maps API Key Restrictions<\/a> for how to configure restrictions correctly.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\" id=\"h-zero-results\">Zero Results<\/h4>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/ecp_location_search_zero_result.jpg\" alt=\"The location search showing zero results\"\/><\/figure>\n\n\n\n<p>Two causes: the API found no match for the search term, or the search term is ambiguous enough that the API returned too many possible matches. For example, searching &#8220;Springfield&#8221; returns results across multiple US states and several European locations \u2014 too many for the API to resolve to a single point. Provide a more specific search term, such as &#8220;Springfield, IL.&#8221;<\/p>\n\n\n\n<h4 class=\"wp-block-heading\" id=\"h-wrong-result\">Wrong Result<\/h4>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/ecp_location_search_wrong_result.jpg\" alt=\"The location search returning a result for the wrong country\"\/><\/figure>\n\n\n\n<p>The API found one result, but it&#8217;s for the wrong location \u2014 for example, searching &#8220;Perth&#8221; returns Perth, Australia, instead of Perth, UK. Add more context to the search term (e.g. &#8220;Perth, UK&#8221;), or use the localization tweak described in the Tweaks section below.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\" id=\"h-multiple-results\">Multiple Results<\/h4>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/ecp_location_search_multiple_results.jpg\" alt=\"The location search showing multiple results for an ambiguous search term\"\/><\/figure>\n\n\n\n<p>The search term is specific enough to narrow the field, but still returns more than one location. For example, &#8220;Springfield, US&#8221; returns three different cities. The site cannot show results when the API returns more than one coordinate. Narrow the search further \u2014 &#8220;Springfield, IL&#8221; resolves to a single result.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\" id=\"h-one-result-success\">One Result (Success)<\/h4>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/ecp_location_search_one_result.jpg\" alt=\"The location search returning exactly one result and showing matching events\"\/><\/figure>\n\n\n\n<p>When the API returns exactly one result, the site takes the coordinates, searches venues within the configured radius, and displays the matching events. This is the only scenario where location search returns calendar results.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"h-key-takeaway\">Key Takeaway<\/h3>\n\n\n\n<p>Location search only works when the Google Maps API can return exactly one, unambiguous result for the search term. The API is the limiting factor \u2014 TEC has no influence over how it resolves search terms, only over what search term is sent to it.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"h-troubleshooting\">Troubleshooting<\/h2>\n\n\n\n<p>If you are outside the United States and location search isn&#8217;t working as expected, the default Google Maps locale (US-based) may be causing issues. See <a href=\"https:\/\/theeventscalendar.com\/knowledgebase\/k\/change-the-google-maps-localization-option\/\">Change the Google Maps Localization Option<\/a> to set the locale to your region.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"h-tweaks\">Tweaks<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"h-add-a-search-tip-for-visitors\">Add a Search Tip for Visitors<\/h3>\n\n\n\n<p>If you&#8217;ve identified a search approach that works well for your site, you can surface it as a tip below the search bar using a template hook:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: plain; title: ; notranslate\" title=\"\">\nadd_action(\n    &#039;tribe_template_after_include:events\/v2\/components\/events-bar&#039;,\n    function( $file, $name, $template ) {\n        echo &#039;&amp;lt;div style=&quot;margin-top: -32px; margin-bottom: 32px; text-align:center; width: 100%; font-style: italic;&quot;&gt;&#039;;\n        echo &#039;When searching for a location, add the state after the city name. E.g. Springfield, MI.&#039;;\n        echo &#039;&amp;lt;\/div&gt;&#039;;\n    },\n    10,\n    3\n);\n<\/pre><\/div>\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/ecp_location_search_snippet_example.jpg\" alt=\"The calendar search bar with the custom tip text displayed below it\"\/><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"h-change-the-location-field-placeholder-text\">Change the Location Field Placeholder Text<\/h3>\n\n\n\n<p>Override the placeholder text in the location field via a template override:<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li>Copy <code>wp-content\/plugins\/events-calendar-pro\/src\/views\/v2\/location\/form-field.php<\/code><\/li>\n\n\n\n<li>Paste the copy at <code>wp-content\/themes\/[your-theme]\/tribe\/events-pro\/v2\/location\/form-field.php<\/code><\/li>\n\n\n\n<li>Edit line 29, which contains the placeholder string.<\/li>\n<\/ol>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/01\/ecp_location_search_placeholder_example.jpg\" alt=\"The location search field with custom placeholder text\"\/><\/figure>\n\n\n\n<p>You can also change the placeholder through translations if you&#8217;re running the calendar in a language other than English.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"h-localize-google-maps-to-a-specific-region\">Localize Google Maps to a Specific Region<\/h3>\n\n\n\n<p>By default, Google Maps uses US locale when resolving search terms. To change this to another region, see <a href=\"https:\/\/theeventscalendar.com\/knowledgebase\/change-the-google-maps-localization-option\/\">Change the Google Maps Localization Option<\/a>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"h-append-a-default-state-or-region-to-search-terms\">Append a Default State or Region to Search Terms<\/h3>\n\n\n\n<p>If all your venues are in the same state or region, you can automatically append that context to every search term before it&#8217;s sent to the Google Maps API. This helps visitors get accurate results without needing to type the state themselves. Replace <code>\"TX\"<\/code> with the appropriate string for your area:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: plain; title: ; notranslate\" title=\"\">\nadd_filter( &#039;tec_google_map_args&#039;, &#039;tec_limit_search_to_texas&#039; );\n\nfunction tec_limit_search_to_texas( $args ) {\n    $args&#x5B;&#039;address&#039;] = $args&#x5B;&#039;address&#039;] . &#039;, TX&#039;;\n    return $args;\n}\n<\/pre><\/div>","protected":false},"excerpt":{"rendered":"<p>Events Calendar Pro includes location-based search, allowing visitors to filter calendar events by proximity to a city, address, or other mappable location. This article covers how to use the feature, how it works under the hood, and how to customize or troubleshoot it. \ud83d\udca1 Location search requires Events Calendar Pro and a Google Maps API&#8230;<\/p>\n","protected":false},"author":5,"featured_media":1955565,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"_kad_blocks_custom_css":"","_kad_blocks_head_custom_js":"","_kad_blocks_body_custom_js":"","_kad_blocks_footer_custom_js":"","_swpsp_post_exclude":false,"_kad_post_transparent":"","_kad_post_title":"","_kad_post_layout":"","_kad_post_sidebar_id":"","_kad_post_content_style":"","_kad_post_vertical_padding":"","_kad_post_feature":"","_kad_post_feature_position":"","_kad_post_header":false,"_kad_post_footer":false,"ep_exclude_from_search":false,"footnotes":""},"categories":[347],"tags":[42],"stellar-product-taxonomy":[158],"class_list":["post-1896653","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-how-to","tag-google-maps","stellar-product-taxonomy-events-calendar-pro"],"acf":[],"taxonomy_info":{"category":[{"value":347,"label":"How To"}],"post_tag":[{"value":42,"label":"Google Maps"}],"stellar-product-taxonomy":[{"value":158,"label":"Events Calendar Pro"}]},"featured_image_src_large":["https:\/\/images.theeventscalendar.com\/kb\/uploads\/2023\/02\/social-share-1024x538.png",1024,538,true],"author_info":{"display_name":"Leah","author_link":"https:\/\/theeventscalendar.com\/knowledgebase\/author\/leahk\/"},"comment_info":0,"category_info":[{"term_id":347,"name":"How To","slug":"how-to","term_group":0,"term_taxonomy_id":347,"taxonomy":"category","description":"","parent":0,"count":109,"filter":"raw","term_order":"0","cat_ID":347,"category_count":109,"category_description":"","cat_name":"How To","category_nicename":"how-to","category_parent":0}],"tag_info":[{"term_id":42,"name":"Google Maps","slug":"google-maps","term_group":0,"term_taxonomy_id":42,"taxonomy":"post_tag","description":"","parent":0,"count":5,"filter":"raw","term_order":"0"}],"_links":{"self":[{"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/posts\/1896653","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/users\/5"}],"replies":[{"embeddable":true,"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/comments?post=1896653"}],"version-history":[{"count":5,"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/posts\/1896653\/revisions"}],"predecessor-version":[{"id":1969930,"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/posts\/1896653\/revisions\/1969930"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/media\/1955565"}],"wp:attachment":[{"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/media?parent=1896653"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/categories?post=1896653"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/tags?post=1896653"},{"taxonomy":"stellar-product-taxonomy","embeddable":true,"href":"https:\/\/theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/stellar-product-taxonomy?post=1896653"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}