Using the Esri World Geocoding Service with Lucity 2019r2

Jonathan Semones -

Starting with version 2019r2, ArcGIS Online service credits will be required to perform certain tasks when the Esri World Geocoding Service has been set as the system default geocoding service within Lucity.

There are many tools, services, and applications provided with Lucity that use a geocoding service.  Some of these tools will take the results of the geocoding service and store them in the Lucity database.  It is this action, saving the results of the Esri World Geocoding Service to the Lucity database, that will start using your ArcGIS Online service credits.  As of 2019r2, the following are the two tools that have the potential to use credits:

  1. Lucity Spatial
    • Lucity offers the ability to store work and inspection spatial components directly in the Lucity database. Storing the spatial component (geometry) in the Lucity database allows for faster analysis, better efficiency, and more flexibility when showing these locations in a map. As records are created, updated, and deleted in Lucity, a Lucity service processes the changes and adds the spatial location (geometry) directly in the Lucity database.  It is during this process, and specifically when calculating the spatial location of an address, that the default geocoding service is used.  The process uses the geocoding service to calculate the xy for a given address and the result (xy) is then stored within the Lucity database.  This is considered a paid operation and will require the use of ArcGIS Online service credits if using the Esri World Geocoding Service.
  2. GIS Scheduled Tasks
    • Scheduled Tasks provide the ability to automatically sync data between your GIS and Lucity products. One of the options when configuration your GIS Scheduled Task is to enable spatial relates for imports.  There is one type of spatial relate that will require the use of ArcGIS Online service credits, the Reverse Geocode. The Reverse Geocode spatial relate type uses the geocoding service to calculate the address associated with the location of the GIS asset and the result (address) is then stored within the Lucity database.  This is considered a paid operation and will require the use of ArcGIS Online service credits if using the Esri World Geocoding Service.

 

As part of this change, starting with version 2019r2, we no longer default to using the Esri World Geocoding Service if a default geocoding service has not been defined in Lucity.  The following is a list of Lucity tools that require the use of a geocoding service and will no longer work with version 2019r2 if there is not a default geocoding service defined within Lucity:

  • Webmap
    • Load Address Subset
    • Show in Map
    • Point Location tool
    • Find Address tool
  • Spatial Updater
  • GIS Scheduled Tasks
    • Export tasks
    • Import tasks that use the reverse geocode spatial relates
  • Work Maintenance/Alternate Zones

 

Use the following guide to determine if your organization is impacted by this change and what actions, if any, need to be taken.

  1. Do you have a Lucity system default geocoding service defined, and is it the Esri World Geocoding Service?
    • No - Since you are not using the Esri World Geocoding Service as the system default this change will not impact your process and no further action is required on your part.
    • Yes - This change has the potential to impact your organization.  If you would like to continue to use the Esri World Geocoding Service as the system default in Lucity proceed with answering the following questions; otherwise, you will need to switch the Lucity system default geocoding service to something other than the Esri World Geocoding Service.  You can find information on creating your own geocoding service here.
  2. Has Lucity Spatial has been enabled?
  3. Do you have any GIS Scheduled Tasks that have the Enable Spatial Relates options checked AND the layer configuration has a Reverse Geocode spatial relationship defined?
  4. Did you answer yes to #2 or #3 above?
    • No - Although the Esri World Geocoding Service has been configured as the system default within Lucity, your organization is not currently using any tools that would require the use of service credits.  This change will not impact your current process and no further action is required on your part at this time.  However, you need to be aware that changes to your current process and/or changes to existing tools or future Lucity tools may trigger the use of service credits.  It is recommended that you go ahead at this time and configure Lucity to use the Esri World Geocoding Service and consider the option to monitor credit usage in ArcGIS Online.
    • Yes - The Esri World Geocoding Service has been configured as the system default within Lucity and your organization is currently using a tool that requires the use of service credits.  You will need to follow the instructions to configure Lucity to use the Esri World Geocoding Service and consider the option to monitor credit usage in ArcGIS Online.

 

Do you have a Lucity system default geocoding service defined, and is it the Esri World Geocoding Service?

  1. In the Lucity Administration tool, go to GIS>>GIS Services…1.png
  2. On the GIS Services dialog, navigate to the second tab, Utility Services.2.png
  3. On the Utility Services tab, under the Geocoding Services section, there will a dropdown populated with the current Default Geocoding Service. Note: if you do not have a default geocoding service defined now is a good time to set one!  There are many Lucity tools that utilize a geocoding service that will no longer work at 2019r2 without having a default specified.3.png
  4. Find the geocoding service record with the same name as the system default from the previous step.4.png
  5. Since the name of the service is user defined, you need to examine the url of the service to determine if it is indeed referencing the Esri World Geocoding Service. The Esri World Geocoding Service url is: https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer (or http).

 

Has Lucity Spatial been enabled?

  1. In Lucity web, open the Admin Portal
  2. In the Admin Portal, click Settings>>System Settings
  3. In System Settings, change the dropdown to GIS
  4. Check the value for the Lucity Spatial- Enabled If set to TRUE, then Lucity Spatial has been enabled.5.png

 

Do you have any GIS Scheduled Tasks that have the Enabled Spatial Relates option checked AND the layer configuration has a Reverse Geocode spatial relationship defined?

Depending on your Lucity GIS integration you will either use the Geodatabase Configuration tool in ArcCatalog or the GIS Configuration tool in Lucity Administration tool to determine if you are using reverse geocode spatial relates with your GIS Scheduled Tasks.  Alternatively, you could run a query against your Lucity database to determine the answer.

  1. Using the Geodatabase Configuration tool, you can manually examine each layer configuration to see if it contains a Reverse Geocode spatial relationship AND it contains a GIS Scheduled Task that has the Enable Spatial Relates option checked. The following is a screenshot showing an example of a layer (pkTree) that meets the criteria:6.png

 

Alternatively, the following is a query you could run against your Lucity database to determine if you have any layers that meet the criteria.  It will return a list of GIS Scheduled Task records that are configured to use reverse geocode spatial relationships.

  • SELECT * FROM CMGISTASKS WHERE TK_GL_ID IN (SELECT DISTINCT ASL_GL_ID FROM CMGISSREL WHERE ASL_R_TYPE = 11)

 

Configuring Lucity to use the Esri World Geocoding Service

Since usage of the Esri World Geocoding Service has the potential to use credits, starting with 2019r2 you must provide Lucity with the credentials to a user in your ArcGIS Online organization that has permissions to use credits.  Lucity will use those credentials to obtain a token that can be used with the Esri World Geocoding Service to perform operations that are not considered free.  Note:  You must upgrade to version 2019r2 to complete the following steps.

  1. In the Lucity Administration tool, go to GIS>>Authentication Setup…7.png
  2. On the GIS Authentication Setup dialog, click Add User.8.png
  3. Provide a description for the credential, populate the username, and set the password.
  4. After you save the credentials to your ArcGIS Online organization go to GIS>>GIS Services…9.png
  5. On the GIS Services dialog, navigate to the second tab, Utility Services, and populate the User Auth field for the Esri World Geocoding Service record using the credentials you created in the previous step from the dropdown list.10.png
  6. Click Save.

 

Monitor Credit Usage in ArcGIS Online

At the time of this writing, Esri uses the following rates for geocoding capabilities:

  • .04 credits to geocode a single address.
  • .04 credits to reverse geocode a single xy location

Usage will obviously be dependent upon many factors, but the impact on your total credit utilization should be minimal.  However, there are some steps we recommend you take to manage and monitor your ArcGIS Online account credit usage, especially for the first few months until you have a better estimate on the amount of credits being used.

  • Create a generic user in your ArcGIS Online organization. This user isn’t tied to an individual.  It would be the account used by automated or unmanned processes.  These would also be the credentials you save with the Esri World Geocoding Service in the Lucity Administration tool.
  • Enable credit budgeting tools in your ArcGIS Online organization. This will let you put a limit on the number of credits a specific user of your organization can consume.  Consider this a safety net that can prevent excessive credit utilization by a user of your organization.11.png12.png13.png

 

  • Set a credit usage limit for the user that you had configured with the Esri World Geocoding Service within Lucity. You could also set a limit for other members in your organization, but for the purpose of this document, we are only concerned with the member that is being used by Lucity.  The amount you allocate to the user is completely up to you, but it is recommended you set it at level you are comfortable with and remember that it can always be increased later.14.png15.png16.png
  • Once the user reaches the limit of their credit utilization, they will no longer be able to perform tasks that consume credits. An email will be sent to the ArcGIS Online account administrator(s) notifying them that the user reached their limit.
  • Finally, you can always monitor credit utilization for your entire organization or a specific member without enabling the Credit Budgeting tools. The following is an example of one member's usage for a specific time period:17.png
Have more questions? Submit a request

Comments