PLUGIN README Geocoder - Automatically geocode addresses in databases or form input, and support searching and sorting by distance. Uses the Google Maps API. ------------------------------------------------------------------------------- OVERVIEW ------------------------------------------------------------------------------- Geocoding is simply the process of taking an address and turning it into a latitude and a longitude. Once you have this information, you can display a marker on a map. Having the latitudes and longitudes of two or more locations is necessary to figure out the distances between them, which allows you to perform searches such as "find the closest 30 results to this zipcode" or "find results within 10 miles of this address." This plugin will attempt to automatically geocode records which have fields called "latitude" and "longitude" as well as any reasonable combination of address fields (see below.) It also provides functions to make searching and sorting by distance simple. USAGE ------------------------------------------------------------------------------- Note: Due to changes to the Google API services as of June 11, 2018, all projects that use Google’s Geocoding API must have an active billing account. Google provides a free $200 credit per month for all billing accounts, which should meet the needs of most sites (40,000 geocoding requests per month, see https://cloud.google.com/maps-platform/pricing/sheet/), but will charge for usage beyond that. For more information on these changes visit https://cloud.google.com/maps-platform/user-guide/. This page also includes a transition tool that can help existing projects get their API keys back up and running. If you are concerned about exceeding the $200/month credit, we recommend setting up quota limits for your project and/or budget alerts. Quota limits provide a hard limit to the number of API requests that a project can make. This is useful to safeguard against exceeding the $200/month credit (or other budget limit), but comes with the risk that if the daily quota limit is exceeded the Geocoding service will stop working until the following day. For more information see: https://cloud.google.com/apis/docs/capping-api-usage To stay under the $200/month credit, set the 'Requests per day' quota for the Geocoding API to 1300 or less. Budget alerts will send a notification when your billing account reaches a specific threshold, but will not prevent it from going over. This is ideal for when you want to be informed of API usage but do not want to risk interrupting service. For more information, see: https://cloud.google.com/billing/docs/how-to/budgets GETTING STARTED ------------------------------------------------------------------------------- First, if you're planning to display your geocoded addresses on a Google Map, you'll need to get an API key. The steps to do this are below (Requires Google account): * Visit https://developers.google.com/maps/documentation/geocoding/get-api-key * Click 'Get Started' * Select 'Maps' and click 'Continue' * Click the dropdown to either select an existing project or create a new one, 'Next' * Follow the steps to create/enable a billing account for this project. * Accept the prompt to enable the Maps API. * Copy the API key and paste it into the value for $GLOBALS['GEOCODER_GOOGLE_API_KEY'], and click 'Done' * The final step is to enable the Geocoding API. * On the Projects homepage, select the APIs from the left hand menu. * Click the Geocoding API link under the Unused APIs menu. * When the Geocoding API detail page appears, click the 'Enable' button. * (Optional) Click 'Secure Credentials' * Under Application Restrictions, select HTTP Referrers * Add the domain for the website(s) this API key will be used on (for example localhost, example.com, 8.8.8.8) * Click API restrictions * Select the Geocoding API from the dropdown * Click Save Next, activate the "Geocoder" plugin in the CMS under: Admin > Plugins. Now click the "Example Code" link beside the Geocoder plugin. When activated, the plugin will automatically create a small, hidden section with 20 records which contain New York addresses, pre-geocoded with latitudes and longitudes. Most of the Example Code pages use this section to show you how you can use the latitude and longitude information you get from geocoding. Browse around the examples to see what this plugin makes possible. AUTOMATIC GEOCODING ------------------------------------------------------------------------------- By default, this plugin will automatically geocode records which have fields called "latitude" and "longitude" as well as an address field combination. For example, if your section contains the following fields, the latitude and longitude fields will be automatically filled in every time you save a record: address city state country Or simply a postal code field: postcode There are many alternative address field combinations which will work. Here is a complete list: address, city, state, zip city, state, zip state, zip zip address, city, state, country address, city, state address Additionally, some fields are recognized with alternate names: state: province zip: zipcode, postcode So, for example, these fields would work: city, province, postcode If you already have address fields in your section, you may only need to add "latitude" and "longitude" fields to start geocoding! NOTE: Automatic geocoding occurs when a record is saved. If you have existing records which need to be geocoded, you can either modify and save each of them, or use the "Geocode Tables" feature, which is described below. DISPLAYING A SINGLE ADDRESS MAP ------------------------------------------------------------------------------- Copy the cmsb/plugins/geocoder/examples/sample_map_single.php file into your web root and make some changes. You'll need to change the "load viewer library" code at the top to match your other viewers. Next, find the "get records" code and change this line: 'tableName' => $GLOBALS['GEOCODER_SAMPLE_TABLENAME'], to reflect the table you want to display records from. You'll also need to strip out the

tag at the end of the page which references some fields in the sample table which you may not have. At this point, navigate to your new page with a browser to make sure everything's working. Now you can add HTML/PHP code for your detail page around the map. If you need a reference for what fields are available, use the Code Generator to create a detail page for your section. DISPLAYING A MULTIPLE ADDRESS MAP ------------------------------------------------------------------------------- Copy the cmsb/plugins/geocoder/examples/sample_map_multi.php file into your web root and make some changes. You'll need to change the "load viewer library" code at the top to match your other viewers. Next, find the "get records" code and change this line: 'tableName' => $GLOBALS['GEOCODER_SAMPLE_TABLENAME'], to reflect the table you want to display records from. At this point, navigate to your new page with a browser to make sure everything's working. Now you can add HTML/PHP code for your list page around the map. If you need a reference for what fields are available, use the Code Generator to create a list page for your section. When a marker is clicked on, an "Info Window" appears in the map, which looks something like a cartoon speech bubble. The content of your Info Windows is set in hidden DIV tags at the bottom of the page. Modify the contents of these DIVs to change what appears in the Info Windows. CUSTOMIZING YOUR MAPS ------------------------------------------------------------------------------- There are many, many ways to customize a Google map. Some changes are easy, while others may require advanced JavaScript. For more information, see the Google Maps Javascript API V3 Reference: http://code.google.com/apis/maps/documentation/javascript/ GEOCODE TABLE FEATURE ------------------------------------------------------------------------------- If you have a lot of records already entered which need to be geocoded, you can use the Geocode Table feature instead of saving them all individually. First, check to make sure your fields are set up properly by saving an individual record then modifying it to see that your latitude and longitude fields have been filled in automatically. Go to Admin > Plugins > Geocode Tables, then select the table which needs to be updated. MANUALLY GEOCODING ADDRESSES ------------------------------------------------------------------------------- This plugin provides a function to manually geocode an address, if you ever find that necessary: list($lat, $lng) = geocodeAddress( @$_REQUEST['address'] ); ------------------------------------------------------------------------------- end of file.