3Geolocation Configuration
Geolocation Coding
Geolocation Coding
Geolocation Coding and Geosearch Overview
Geocoding a location, or geolocation coding as it's referred to in Sourcing, means assigning geographical coordinates, latitude and longitude, to that location; a city such as San Francisco is identified by those coordinates instead of its name in text. Once you have your locations geocoded, you can choose to enable Geosearch within Sourcing which provides several benefits.
Geocoding and enabling Geosearch is optional. When enabled, the following benefits are available:
-
Radius Search Functionality - allows jobseekers to search for jobs within a defined perimeter around a location. For example, you may search for all jobs within a 50 mile perimeter of Paris.
-
Automatic suggestions of locations when the jobseekers begin to type letters in the Location Search field.
-
Radius search within the Automated Referral Campaigns (ARMs).
To enable Geosearch the locations in the location tree in Recruiting must be geocoded. The latitude and longitude coordinates that we use for geolocation coding reside in a repository that requires standardized location details to retrieve the proper coordinates. The required format of the location details is country, region/state and city. The location tree in Recruiting must exactly match the repository standards of country, region and city to retrieve the correct coordinates, or geolocation. If the location hierarchy does not match the standards, or if perhaps a location name is misspelled, the geolocation coding will fail and as a result, the candidates search experience may be degraded as not all of the Geosearch capabilities will be functional. To provide the best results and experience with Geosearch, it is critical that time and effort be spent upfront ensuring that locations are geocoded correctly.
Prior to enabling Geosearch, the location tree structure and names need to be validated. If the structure is inconsistent or not standardized with the levels needed for geolocation coding; country, region/state and city, then preliminary work in Recruiting will need to be done to standardize the location tree.
The location tree must be precise and consistent for geolocation coding, and consequently Geosearch, to work properly. The locations in the location tree that are not standardized or contain spelling errors will not be geocoded. This means if you post jobs on these locations, jobseekers will not find these jobs when they search on the locations that have not been geocoded. To prevent this, you can either manually geocode the locations by entering coordinates in Sourcing or disable Geosearch.
Geocoding Principles and Architecture
Sourcing attempts to automatically assign coordinates to all locations. This process uses several processes and databases including the following:
PlaceFinder
-
Provides a list of locations when a user starts to type
-
Contains a database of all locations and their coordinates sourced from NavTeq and Geonames.org
-
Can be configured to show cities in specified countries
-
Displays locations in the users language
eLocation Server
-
Provides coordinates for the locations during the geocoding process
-
Contains a database of all locations and their coordinates sourced from NavTeq and Geonames.org
-
Requires a city, state/region and country as input
Solr
-
Solr is a keyword search engine. This means that you can give this engine a piece of text such as, "Father went to the grocery store" and it will be able to find this text as it searches for, "groceries." Geosearch relies on four Solr cores:
Location Exception Core
-
Stores additional or customized locations coordinates not covered by the eLocation server
-
Job Load
First, jobs are loaded into Sourcing from Recruiting via the API. During this loading process, we identify new job locations and try to assign them coordinates.
-
Geocoding
We look for a coordinate in the Location Exception Core. This core stores all locations that are not found in our third-party vendor's database. It also contains fixes and modifications to incorrect data by our vendors. We send the triplet country, state and city to the Oracle eLocation Geocoder to get the coordinates. If a coordinate is not found, an Administrator will need to manually assign coordinates to this location.
-
Index Jobs
After the job locations are geocoded, the Solr Job Core pulls all the jobs from the database into itself. It then indexes all the text from the title, description, qualifications, company, category, and of course, the coordinates.
-
Search
-
The jobs are now ready to be searched. When a job search is performed, Sourcing constructs a Solr query and sends it to Solr using their REST API.
Configuring Geolocation Coding to Enable Geosearch
Analysis of the Location Tree Structure
The location tree in Recruiting is configurable and as a result, the levels in the tree may not be consistent with the levels used in Sourcing that are required for geolocation coding. Sourcing relies on country, region/state and city. All countries, regions/states and cities must be at the same level of the tree; you cannot mix different structures within the same tree. The tree structure in Recruiting must exactly match the mapping in Sourcing or geolocation coding will fail.
The tree structure in the image below will cause geolocation coding to fail. You can see that the United States follows the structure required for geolocation coding, which in this example is country at Level 1, region or state at Level 2 and city at Level 3. However, Spain has cities in Level 2 of the tree instead of the required regions/states.
If the location tree structure is not consistent and does not meet the requirements for geolocation coding in Sourcing, the tree must be modified in Recruiting.
Analysis of the Location Names
The repository used to return the coordinates for geolocation coding recognizes only the official names of countries, regions/states and cities. If the names are misspelled, abbreviated, customized, etc., they will not be recognized and therefore, not geocoded.
It is considered best practice to refer to Wikipedia for the proper names of countries, regions/states and cities.
Mapping Configuration
Once you've verified the location tree structure and the names contained within the tree are accurate, you can configure the mapping in Sourcing to the location tree in Recruiting.
Path: Sourcing > Configuration > Taleo > [Taleo Enterprise Edition]
You need to indicate at which level the values for country, region/state and city can be found here. Municipality and address are not required for geolocation coding, but may be configured for other purposes. Once the mapping is configured, click the Refresh button to refresh the Job Location Levels.
Trigger Geolocation Coding
Geolocation coding is automatically performed when the OLF levels are synchronized or when the jobs are loaded into the system. However, if for example, you have just made changes to your OLF mapping configuration and refreshed the location levels, you need to go into the Geolocation Editor in Sourcing to trigger the geolocation coding.
Triggering geolocation coding in Sourcing erases manual geocoding that you may have done. Therefore, it is highly recommended that you first back up your geocoding prior to triggering the geolocation coding.
Path: Sourcing > Configuration > Geolocation > [Geolocation Editor] > Click here to view the editor
To create a backup file of your current geocoding, click the Click here to view the editor. The editor opens and you will select the Job Locations tab and then click the Backup Job Geolocation Data button. Now that your prior geocoding efforts are saved, you can trigger the new geolocation coding.
Path: Sourcing > Configuration > Geolocation > [Geocoding - Job Locations] > Geocode Job Locations
Click the Trigger button to initiate geolocation coding based on your new location mapping configuration. This action may take up to an hour depending on the number of jobs and locations you have to geocode.
Verify the Geolocation Coding Results
After the job location geocoding process completes, you should to back to the Geolocation Editor to verify that your locations have been geocoded properly.
Path: Sourcing > Geolocation > [Geolocation Editor] > Click here to view the editor
You can filter your geocoding results using the different tabs. You can see that your locations have now been assigned latitude and longitude coordinates and have been successfully geocoded. If your locations were not geocoded, you should review the location tree in Recruiting and verify the structure and names are accurate and also review the mapping configuration in Sourcing.
Troubleshooting and Correcting Failed Geolocation Coding
There are several reasons that geolocation coding may fail. Here, we'll discuss the possible reasons for failure and how to address each.
The most common reasons that a location may fail to be geocoded include:
-
The name is incorrect - the misspelling of country, region/state or city will cause geocoding to fail.
-
The location mapping configuration is incorrect - if country, region/state or city in the Recruiting location tree are not placed at the levels indicated in the Sourcing mapping configuration, or if a level is missing, geocoding will fail.
-
The location is not found in the eLocation server nor in the Location Exception core server.
Now, let's take a look at how to correct each of these potential issues.
Incorrect Name
-
Make certain that the regions/states are formatted correctly without abbreviations. For example, a state should never be listed with its abbreviation, e.g., Calforina, CA.
-
Make certain you've provided the actual city name and not a district within a city.
-
Verify the region of the state that hosts a city. Some cities have a unique status and are a state in and of themselves, e.g., Buenos Aires contains cities even though it is in the country of Argentina.
If you identify that a location name is incorrect, you can correct it one of two ways: you can change the name of the location or provide the geocoordinates for the location.
Changing the Name of the Location
You can change the name in either Sourcing or Recruiting. To change the name in Sourcing, go to the Geolocation Editor and edit the Job Location.
Path: Sourcing > Configuration > Geolocation > [Geolocation Editor] > Click here to view the editor
Click the Edit link next to a location that was not geocoded.
When you click the link, click the Edit Location button in the modal that opens. You'll then be able to enter new values for city, region/state and country. When you click Submit, Sourcing immediately attempts to geocode the location with the new information you provided.
Providing the Geocoordinates for the Location
To provide the geocoordinates for the location, you follow the same path as above for editing the location as both editing the location and editing the coordinates are done in Sourcing using the Geolocation Editor. Instead of clicking the Edit Location button, click the Edit Coordinates button and enter the latitude and longitude for your location.
Again, you can refer to Google Maps or Wikipedia to obtain these coordinates. They can be easily found by googling name of city coordinates, e.g., San Francisco coordinates. The first number provided is the latitude and the second is the longitude. South and West must be entered as negative and North and East as positive.
Incorrect Location Mapping Configuration
Check the read-only mapping you have provided in Sourcing in Sourcing > Configuration > Taleo > [Taleo OLF Structure] and look for the location not geocoded in your location tree. Validate that you find a country, state and city at the levels indicated in your mapping. It this is not the case, you need to modify your location tree in Recruiting to correct the mapping. Once you do this, the geocoding will not be triggered immediately. There must be OLF synchronization between Recruiting and Sourcing fore the location is geocoded again.
Location Not Found in eLocation Server nor in Location Exception Core Server
The repositories that we use to retrieve the coordinates for geolocation coding are stored in an eLocation server and in a Location Exception Core server. It is possible that the locations you would like to geocode are not present in either of these servers. If that is the case, Sourcing is not able to geocode these locations automatically as it relies on the coordinates contained in the repositories on these servers to do so. If you've first verified that your names are spelled correctly and that your location configuration mapping is accurate, and your locations are not being geocoded, you can look in these two servers to see if the problem is that your locations do not reside in either.
Looking for a Location in the eLocation Server
eLocation provides an interface that allows you to send a query to search for your location. To query the eLocation server for your location simply replace the city, state/region and country in the query below with your specific location.
http://elocation.oracle.com/geocoder/xmlreq.html
<?xml version="1.0" standalone="yes"?> <geocode_request vendor="elocation"> <address_list> <input_location id="27010"> <input_address match_mode="relax_base_name"> <gen_form city="CITY" region="REGION" country="COUNTRY"/> </input_address> </input_location> </address_list> </geocode_request>
Once you've replaced the city, state/region and country with your location information, click Submit. You will either be presented with your coordinates or a message indicating that the country you are searching for is not supported in eLocation.
Looking for a Location in the Location Exception Core Server
At this time, there is no interface that allows you to query this server, so you will need to create an Oracle Service Request with Support to retrieve the geocoordinates. Currently, the following countries are supported by the Location Exception Core server:
-
China
-
Gabon
-
Iraq
-
Israel
-
Japan
-
Korea
-
Myanmar
-
Pakistan
-
Senegal
-
Serbia
-
Taiwan
-
Yemen
Geolocation Editor
Administrators can edit and add geolocation parameters using the Geolocation Editor.
The Geolocation Editor displays which locations are geocoded and which are not. When data comes in that is not geocoded, the Geolocation Editor allows Administrators to geocode these locations by entering latitude and longitude parameters. Some locations do not have geolocation coordinates, such as rural areas or cities that are not incorporated. By entering the latitude and longitude manually in the Geolocation Editor, these locations can then be found using geolocator functionality. The Geolocation Editor provides the ability for Administrators to edit the geocoding of their locations to be certain those locations are properly placed. Users can search for locations, edit geocoding details of those locations, and then, re-trigger geocoding.
Locations are easy to find using the filters and sorting capabilities in the Geolocation Editor. Administrators can filter and search job locations and company offices as well as sort the locations in either ascending or descending order. The filter criterion available differs depending on whether you are searching for job locations or company offices.
Path: Sourcing > Configuration > Geolocation > [Geolocation Editor] > Click here to view the editor
Geolocation Customization Backup and Restore
When a full refresh of all jobs via the Job Connector is performed, all new locations are imported and previously entered Geolocation customizations are removed. Administrators have the option to backup and save their custom Geolocation latitude and longitude values for job locations to eliminate the need to reconfigure customizations.
This backup feature creates a single cloud-based file for geocoded locations which can be used to easily restore the customizations. Only a single file is created and saved in the cloud and previous backups are not available. For this reason, Administrators have the option to export each file into an Excel format that can be saved for later reference.
After entering geolocation customizations, Administrators click the Backup Job Geolocation Data button. Their customizations are saved in the cloud until another backup is performed. When another backup is performed this file gets overwritten, so if Administrators want to keep each of their backups, they must export the cloud files into Excel. This is done by clicking Download backup file. Once a job refresh is run, the customizations are removed, and can then be restored by clicking the Restore Job Geolocation Data button.
Disable Browser Geolocator
Administrators can disable the location services that prompts users to share their location.
Administrators can choose to disable the browser geolocator without disrupting the PlaceFinder functionality. When the Use Browser Geolocation setting is on, and the user has no previous settings for the site's URL in their browser, the location services will prompt the user for sharing their location. When the setting is off, and no privacy settings were previously set, then the user will not be prompted to share their location. This setting is found in Configuration > Geolocation > Geo Search > Use Browser Geolocation.