Monday Knowledge Snippet (MKS) – 60 Location Geo-Coding
Stumbling over the topic Location Geo-Coding last week which is pretty important for the transportation network data quality and having to dig deep into it again, it is probably a good idea to write it down and share.
Geo-Coding is a function to enrich the Location master data with geo-coordinates based on their address fields (Note that the location is no TM specific master data object, but located in the SCMB. So all of this is also relevant for applications sitting on top of the SCMB like EWM.). Those coordinates define the more or less accurate position of this location on earth. Coordinates comprise longitude, latitude and altitude (I am actually not aware of any standard process using this altitude, but in a CD project it could be used [incompatibility, ….]). In the location transaction you see longitude and latitude in degrees, minutes, and seconds. In the database table (/SAPAPO/LOC) you find those fields in GPS format in fields xpos and ypos. For each location you have in addition the information on which precision level the geo-coordinate could be determined (from unspecififed over world up to house number).
The most important usage of this information is the distance determination. This determination is required when creating a transportation lane (system makes proposal for distance and duration), creating TM business documents having stages, and running automatic transportation planning. Especially for planning the distance and duration data quality is crucial having a strong impact on the result quality of the transportation plan created.
The second use case is the display of the locations (either standalone or as start/destination of a transportation lane, schedule, or TM business document like a freight unit or freight order) on the SAP TM geo-map component. Without an accurate coordinate you will se results completely confusing for the user.
Location displayed on Geo-Map using SAP Visual Business
Geo-Coding is applied whenever a location is created or relevant address fields are changed. This can either be:
- manually in the location transaction
- in background when uploading or transferring locations (CIF from SAP ERP)
- Note that the Geo-Coding can be disabled for the upload. When your locations already have accurate geo-coordinates attached and you do not want the system to overwrite those, the function module /SAPAPO/LOC_MAINTAIN_CIF on SCM side has the parameter IF_NO_GEOCODING. This can be set in the BAdI SMOD_APOCF001 interface method IF_EX_SMOD_APOCF001~EXIT_/SAPAPO/SAPLCIF_LOC_001 using parameter EF_NO_GEOCODING.
- manually creating a Transportation Request in TM
- during order integration from ERP
The special case related to the orders is connected to the one-time location topic: SAP TM creates for those documents having stages based on address information so-called one-time locations. And for those of course also Geo-Coding is applied. See MKS10 One-Time Locations.
Geo-Coding is by default applied like defined in the standard customizing under SAP NetWeaver -> General settings -> Set Geocoding.
Here the to-be-used Geo-Coder can be defined per country. In standard all countries are assigned to Geo-Coder ‘SAP0’. This Geo-Coder accesses geo-coordinates stored in the system for countries and regions. Those geo-coordinates can be adjusted or added in the activities ‘Process Geographical Data for Countries’ and ‘Process Geographical Data for Countries and Regions’. From a TM use-case perspective, this information is more or less useless. Neither can the transportation planning run well on such coordinates, nor can the location be displayed correctly. It is a fallback to have at least a grouping on country/region level. Note that there is no such geo-coordinate logic available based on postal codes (what would improve the ‘SAP0’ logic already quite a bit).
To improve the Geo-Coding quality, the standard comes with the option to connect to an external GIS using the SAP IGS infrastructure using Geo-Coder class ‘CL_GEOCODER_IGS’. Check the documentation for activity ‘Register Geocoding Program in the System’. This setup passes the address information to a real GIS and receives good quality geo-coordinates. Important to know is that SAP TM is not shipped together with the required product since a long time, but SCM still is.
It is possible to enhance the Geo-Coding here by defining a custom Geo-Coder and connect to the desired source. To do this, a class implementing interface IF_GEOCODING_TOOL is required which can be entered in this activity. Note that for the TM use case another more direct enhancement option exists, which I will explain later. But if you have already set this up, you can of course keep it running also when using the GIS integration framework.
Custom Geo-Coder class
In the country assignment it is possible to select from all available Geo-Coders and give those a sequence. For example I can say I prefer my custom Geo-Coder ‘ZCGC’ for Hungary, but want as fallback still ‘SAP0’. In case I delete the ‘SAP0’ entry, the system should leave the coordinates initial when the Geo-Coder does not return a result or can not be reached. This was not working this way when using the new GIS integration framework, but was corrected with note 2219651.
Geo-Coder Country Assignment
GIS Integration framework based on the Process Controller
For improvements for a streamlined Geo-Coding and Distance determination, it was required to have a more flexible framework which was delivered with SAP TM 8.0. This framework is based on the Process Controller (MKS03) and uses Geo-Coding levels. More details can be found in MKS07 Geo-Coding levels. Basic idea is that you can on SCM level define a strategy you want to apply for Geo-Coding (either the standard using the NetWeaver framework or a custom strategy).
Geo-Coding level definition
By default, this definition is empty meaning the standard NW Geo-Coding is applied. But now a specifc GC level can be added. Pointing to the delivered standard strategy GC_STD the effect is the very same like no GC level, but you could for example point to a custom strategy. The usage of the standard strategy GC_STD makes sense when you have multiple GC levels, which is only required for a performance improvement for distance determination.
Important to know is that the coordinates on the most detailed GC level must be in synch with the location header coordinates.
Geo-Coding level definition
Check and correct
Especially for the mass background processes it is quite cumbersome to check the application log or each location if the Geo-Coding returned sufficient results. For this the report /SAPAPO/MASS_GEOCODE_LOC can be used enabling a quick check (display) of selected locations, but also a simulation and correction of all or specified GC-Levels. This report has been enhanced with note 2218006 and should now cover the known requirements (keep manually maintained coordinates, selection by zone, selection by used source).