Start of Content Area

Function documentation Interface for Third-Party Geo-Coding  Locate the document in its SAP Library structure

Use

SAP provides an interface for third-party vendors of geo-coding programs. This interface describes how a company developing geographical information systems (GIS) can attach its geo-coding program to the SAP system. Thus, third-party vendors can offer a complete geo-coding package with regard to implementation, delivery, and Customizing.

Prerequisites

The geo-coding interface is valid for SAP's basis releases 4.6C, 4.6D, and 6.10.

Note

You are not required to set up a user interface. The dialog box for selecting an address is part of the SAP geo-coding framework.

Features

Internal Structure of Geo-Coding Framework

The SAP system uses a geo-coding framework that provides a dispatcher. The dispatcher enables you to choose between several geocoders for a given address and an interface to ABAP applications. The application calls this dispatcher in order to pass one or more addresses. The dispatcher chooses the correct geocoder (depending on the country where the address is located and on Customizing settings), and then calls it via the geo-coding interface.

The following figure shows the geo-coding framework from the left (application) to the right (geo-coding program). The relevant part for geo-coding program suppliers can be found in the right-hand section of the figure (colored red), including the “Interface to geo-coding programs”.

This graphic is explained in the accompanying text

 

Data Exchange Between the SAP Geo-Coding Framework and the Geo-Coding Program

This graphic is explained in the accompanying text

Attachment of Geo-coding Programs to the SAP System

You can attach your geo-coding program to the SAP system using:

         the ABAP IF_GEOCODING_TOOL interface or

         the RFC interface.

For more information about the different parameters and data types used, see

         Parameter Description

         Data Types of the ABAP interface

         Data Types of the RFC interface

ABAP IF_GEOCODING_TOOL Interface

To attach a geo-coding program to the SAP system via the IF_GEOCODING_TOOL interface, you must first implement a class in ABAP/OO. This class must then implement the IF_GEOCODING_TOOL interface. This interface defines the GEOCODE method as follows:

method if_geocoding_tool~geocode

 

importing

addresses

type

aes_addr_table

 

 

xinfo

type

geocdxinfo

 

exporting

results

type

geocd_res_table

 

 

choice

type

geocd_choice_table

 

 

relevant_fields

type

geocd_addr_relfields_sortedtab

 

changing

corrected_addresses

type

aes_addr_sortedtable

 

 

messages

type

aes_msg_table

 

 

containers

type

aesc_sortedtable.

The interface always works with tables and is able to run mass transactions. Each address carries an identifier ( GUID16) for identification purposes. The geo-coding program needs to assign the identifier to all calculated results. Within this documentation, only one address is passed to the method for simplification purposes.

RFC Interface

To attach a geo-coding program to the SAP system via the RFC interface, you must implement an RFC server and use SAP's generic geocoder class to call it via RFC. The RFC destination and geocoder function name can be maintained in the geo-coding customizing settings. The ABAP class ( CL_GEOCODER_GENERIC_RFC) simply maps the given parameters to RFC-safe structures and passes them to the RFC server, which you must implement.

We recommend that you use a function name such as RFCGEOCODER_pv_c, where pv is a product identifier and version number, and c your company identifier. The maximum length of such a function name is restricted to 30 characters. For example, an SAP geocoder could use a name such as RFCGEOCODER_GC10_SAP.

This interface is as follows:

RFC_FUNCTION name_is_up_to_you

 

importing

addresses

type

aes_rfc_addr_table

 

 

xinfo

type

geocdxinfo

 

 

time_zone

type

timezone

 

exporting

results

type

geocd_res_table

 

 

choice

type

geocd_choice_rfc_table

 

 

relevant_fields

type

geocd_addr_relfields_sortedtab

 

changing

messages

type

aes_msg_table

 

 

containers

type

aesc_rfc_sortedtable

 

 

container_lines

type

aesc_cont_sortedtable.

Differences Between IF_GEOCODING_TOOL and RFC Interfaces

A few arguments have changed in the RFC interface. These changes come from the fact that the address type has been changed from ADRC_STRUC in the OO interface to GEOCD_ADDR in the RFC interface. Addresses occur in exactly these two arguments.

The argument time_zone has been added. This makes it easier for you to return the required time zone. Note that all addresses passed always come from the same country. Thus we pass only one tzone, which is valid for all the addresses in the respective country. This method works fine for countries with just one time zone and you only need to return this value. If you write a geocoder for a country with multiple time zones, such as the US or Russia, it is your job to determine the correct time zone for a given address.

The argument corrected_addresses has been omitted because the SAP geo-coding framework corrects the addresses on its own.

The arguments choice and containers have been changed due to restrictions in RFC calls (no tables in tables). Argument container_lines has been added and is now used in conjunction with choice and containers.

Note

We recommend the RFC approach for the following reasons:

-         There is no requirement to write ABAP coding.

-         Certification and/or validation is easier.

Example for a result in container_lines

The address with ID=AF6C32 could have been geocoded (which can be seen by the zero in column COUNT), while the address with ID=FCA753 is ambiguous (two entries with COUNT=1 and COUNT=2). Thus, address FCA753 has two corresponding entries in table CHOICE, while address AF6C32 has a corresponding entry in table CONTAINERS.

ID

COUNT

SERVICE

FIELD

VALUE

FCA753…

1

GEOCODING

LONGITUDE

1.234

FCA753…

1

GEOCODING

LATITUDE

34.243

FCA753…

2

GEOCODING

LONGITUDE

-53.987

FCA753…

2

GEOCODING

LATITUDE

12.433

AF6C32…

0

GEOCODING

LONGITUDE

38.432

AF6C32

0

GEOCODING

LATITUDE

-84.342

Activities

Customizing Settings

1.       In Customizing for General Settings, register your geo-coding program in the SAP system by selecting Geo-Coding Register Geo-Coding Program in the System.

Enter the value for SRCID that you received from SAP and the name of your class. When using an RFC interface, the third-party vendor can have his own SRCIDs.

Save your entry. From now on, the SAP system only works with SRCID.

2.       Set up a country for your geo-coding program in Customizing for General Settings by selecting Geo-Coding Assigning Geo-Coding Program to Countries.

Create a new line for the desired country, enter the value for SRCID that you received from SAP, and enter a value for the sequence. If there already is an existing line entered for this specific country, select a number smaller than this one.

Set the exclusive flag.

3.       Mark all fields of the ADRC_STRUC address structure that will be used to determine the geographical location in Customizing for General Settings by selecting Geo-Coding Assign Relevant Address Fields for Geo-Coding for each attribute used in your geo-coding process. First enter the ID of your geo-coding program, then enter a value in the address field (or press F4 for a list of possible attributes).

Note

To test it, run the GEOCODING_FIRST program. It is a very simple program that lets you enter an address and prints out the values returned from the geo-coding program. As this is only a test program, we recommend using it as an entry point for your test program. You can also use this program for testing the SAP geo-coding program SAP0 that works on a country/region basis.

Keep in mind:

         You are not required to write a geo-coding program for all countries at once.

         It is possible to use more than one geo-coding program.

         It is possible to set up the system for using specific geo-coding programs for specific countries.

Example

Fine-Tuning the Customizing Settings

A customer wants to use two different geo-coding programs for the same country (for example, France): a reasonable version that works on a regional basis in France (for example, the SAP0 geo-coding program that is contained in the standard delivery) (Geocoder1), and one that works at street level for Paris as capital of France (Geocoder2) for routing purposes.

You can set up Customizing in two different ways:

1.       Run Geocoder1 to get a valid geographical location somewhere in France, and then improve it by trying Geocoder2, which may improve the location if it is in Paris.

In Customizing for General Settings, select Geo-Coding Assign Geo-Coding Program to Countries. For France, Geocoder1 needs to get a value for the Sequence column that is smaller than Geocoder2 to make the program run earlier. But although Geocoder1 may succeed, we need to run Geocoder2, which may improve the result of Geocoder1. This requires that you remove the exclusive flag in Customizing.

This solution requires that you ALWAYS run both of the registered geo-coding programs, even for addresses in Paris.

2.       Run Geocoder2. Only if the address is not located in Paris, start Geocoder1.

In Customizing for General Settings, select Geo-Coding Assign Geo-Coding Program to Countries. For France, Geocoder1 needs to get a value for the Sequence column that is higher than Geocoder2 so that the program runs later. If Geocoder1 succeeds (because it found an address in Paris), Geocoder2 does not need to be run because there is no chance for it to improve the location. For this set, the exclusive flag of Geocoder2, which means „Do only continue if no result (result=6 -> not responsible

class=Section2>

) was determined.“ If this flag is set once for a geo-coding program, all geo-coding programs for the same country with a higher value in the Sequence column are implicitly set as exclusive.

This is the preferable solution because of its higher efficiency, but it requires the geo-coding program with the higher order value to be able to improve on an already existing location.

 

 

End of Content Area