Basic Setup

Providers

For the initial setup, we recommend using OpenStreetMap and Nominatim, because these are not only free to use, they also don't require any additional provider setup steps. You select them in the providers options and you are done.

Mapbox, Google and ArcGis (for geocoding only) require additional steps to generate API keys, etc.

Having said this, free doesn't mean better. While the free option may be enough for most use-cases, you need to evaluate how it works for you. Things like up-to-date information, quality of map layer, and quality of service may play an important role on your site.

Many clients have found that the Nominatim geocoding service is not always able to geocode an address than can be easily geocoded by one of the other providers.

While all providers offer the same type of functionality within the Add-on, Google and Mapbox have some features not available with OpenStreetMap.

• Google and Mapbox offer static map images used to display map covers in listing detail pages
• Google and Mapbox allow creating custom style maps, although Mapbox seems easier through their Mapbox Studio tool.
• Google is the only provider with streetview functionality for listing detail pages

The Google Maps Platform is the most complex to set up, so there's a dedicated page in the documentation. Read more on setting up Google Maps.

Creating Custom Fields

To continue you need to have, at least, the following custom fields in JReviews Custom Fields Manager:

• Address (Text)
• Latitude (Decimal)
• Longitude (Decimal)

Other than these, all the other fields in the Add-on setup are completely optional.

Need a refresher on creating fields and field groups? Check the initial setup.

You can of course expand the address-related fields to include Country, State/Region, City and Postal codes if you want to list these separately.

Postal Codes

For postal codes, or zip codes, we recommend using a text custom field. This is the standard across the large majority of sites. Otherwise you may end up with a select list with thousands of options. Don't use an integer field, especially for US addresses, because integers can't have leading zeroes in them.

Select Vs. Text Fields

It's really up to you which type of field you prefer to use. The map and location-search features are based on coordinates, so once a listing is geocoded, the address itself doesn't matter from a code-perspective.

Select Custom Fields

• Consistent data.
• Allows field option relations (e.g. State → City).
• Can be used in advanced search/filtering showing the field options.
• Can be used for navigation as virtual categories

Text Custom Fields

• Simpler setup since you don't need to worry about relationships.
• Automatically fill address fields through address autocomplete. For example, type an address, choose a suggestion and the individual fields are automatically filled out.

One Location per Listing

A listing can only have one location because the listing is the location/place. That means only one address and one set of coordinates.

If you have a business with several branches, you would need to create one listing per branch, each with it's own address.

One Set of Location-Based Fields for the Site

When you create the location fields, use a dedicated field group, like "Address" or "Location" to place the fields. Then in each listing type where you'd like to show maps or have location-based search, associate this "Location" field group.

Avoid creating multiple, duplicate, location fields like "Business City", "Restaurant City", and so on, because you can only use one city field with the Add-on.

Reminder When Creating New Fields

If you didn't create the necessary fields in your initial JReviews setup, you can always create them later following the above recommendations.

A few reminders when creating custom fields:

• For a custom field to appear in the listing form, the field's field group needs to be associated with the listing type for that listing. So if you are also creating a new field group, make sure you go back to your listing types and include the new field group.
• If you also use PaidListings and you already have listings with paid orders. You need to go back to your pricing plans, select the new custom fields you just created, save the plan, and use the button to update existing orders for that plan.

Setting up Custom Fields

After creating all the necessary fields, go to the Add-on's Configuration page and scroll down to the Address Fields section. Here you will associate each setting with the corresponding custom fields that you created.

Map It Field

This isn't a new custom field you need to create. Instead, the setting allows you to specify which of your existing custom fields in the listing form be used to attach the Map it functionality. This can be the address field, or any field for that matter.

When Map it is clicked, all address field information will be used to automatically
geocode it into coordinates and a map dialog will be presented, allowing further adjustment of the marker location on the map.

The Map it functionality is optional so you don't have to fill out the setting. You can also enable automatic geocoding on new listing submissions. Both functionalities can also be used together. If Map it is not used, then the listing will be automatically geocoded when a new listing is saved.

If you are importing listings with the Import Add-on without including coordinates. An extra step will be required to geocode those listing addresses. The Add-on includes a batch geocoding functionality in the Add-on admin control panel for this purpose.

Location Search

Similar to the Map it field, it's necessary to tell the Add-on which custom field should be used to attach the proximity search functionality. In the majority of cases, you'll use the field you setup as the Address (jr_address) field.

When using Advanced Search and Filering, all you need to do then is include this field (e.g. jr_address) in the form and whenever an address or partial address is typed there, it will be automatically geocoded into coordinates in the background to perform the proximity search.

Address Autocomplete

You can enable address autocomplete functionality for the location search field you setup above. This will show address suggestions to the user while typing an address to perform a location search. This feature works in search forms and also the listing form.

My First Map!

Lets test the setup to display the first map on the site.

• If you set up the Map it feature, you can update or post a new listing and use that to geocode the address, save the listing, and visit the listing detail page.
• If instead you are relying on automatic geocoding, without Map it, you can create a new listing, or for listings that already have addresses, use the admin control panel Geocode Addresses functionality. There you can individually geocode listings, using the pin icon to the right of any listing, or run the batch geocoder using the Geocode Addresses button. When done, visit one of the listings in the front-end.

What if you can't see the map?

1. Edit the listing and see if the coordinates are filled out. No coordinates → No maps. If you changed the Access Settings for coordinate custom fields, make sure they are at least available to use as an admin user, and ensure that the fields are published.
2. Go to your listing type and make sure maps are enabled for lists and detail views. You'll find a couple of settings there. Even if enabled, try saving the listing type again, clear caching and re-visit the page on the front-end.
3. If you are using PaidListings, make sure you added the fields to the paid plan for the listing and used the update orders icon for that pricing plan.

Deferred Loading

Any map provider you choose needs to make requests to external servers to load the map scripts, retrieve the map tiles, etc. Paid maps like Google and Mapbox will count these requests as API requests towards your plan limits.

The Add-on has a feature that allows deferring the loading of the maps until the site visitors wants to interact with the map. You can enable it separately for different types of pages in Configuration → Basic Setup → Enable "Show map" button.