Using Build Global Address

Building an address is an interactive process that requires you to select address elements at each step of the address building process. This means that building an address requires a sequence of calls to Build Global Address, not a single call. To start, you make an initialization call to Build Global Address. This call returns a session ID. You then use this session ID in subsequent calls. With each call, Build Global Address presents a list of alternative values for an address element. You select the value you want, then move on to the next address element until the complete address is built. With some exceptions, you need to make a separate call for each address element.

The overall process works like this:

  • First, you make an initialization call to open a session and receive a system-assigned session ID.
  • Make a search call to find possible values for a given address element.
  • When you have selected the value you want, you make a commit call to indicate the value you want for the given address element.
  • Continue to make search/commit calls until all address elements are committed.
  • Finally, you make a close call to end the session.

To familiarize yourself with how the process works, use the Management Console's Preview tab to step through the following procedure.

  1. Open the Management Console.
  2. Under the Services tab, select Address Now.
  3. From the list of services on the left side of the pane, select Build Global Address.
  4. On the Options tab, specify the options you want. For information on the options, see Options.
  5. Click the Preview tab.
  6. In the Action field type init.
  7. In the Country field enter the country of the address you want to build.
  8. Click Run Preview.
  9. In the Preview Output, find the SessionId field, highlight and right-click the value, and select Copy from the pop-up menu.
  10. In the Preview Input, highlight and right-click the SessionId field and select Paste.
  11. Enter the following values in the input fields:
    • Action—Type search.
    • Country—Keep this field the same.
    • FieldIndex—Type the index value of the first field you want to search. For example, if you know you want to search for an address in Chicago, you would type "1" because for U.S. addresses, field index 1 corresponds to the City field.
    • SearchValue—Type the value you want to search for. For example, if you want to build an address in Chicago, you would type "chicago".
    • SessionId—Keep the same value.
    Note: The values in the other input fields are ignored.
  12. Click Run Preview again.
  13. The results of the search are placed in up to two output fields: Alternatives.InContext and AlternativesOutContext. For an explanation of the difference between in context results and out of context results, see What Is Context?.
  14. When you have found the value you want, enter the following values in the input fields:
    • Action—Type commit.
    • AlternativeIndex—Type the index number for the alternative you choose. Index values start with 0, not 1. For example, if you search for Chicago, the alternatives returned by Build Global Address would be indexed as follows. If you want to commit the value "CHICAGO" you would type "0" in the AlternativeIndex field.
      • 0—CHICAGO
      • 1—CHICAGO HTS
      • 2—CHICAGO PARK
      • 3—CHICAGO RIDGE
      • 4—EAST CHICAGO
      • 5—NORTH CHICAGO
      • 6—WEST CHICAGO
    • AlternativeContext—Type in or out to indicate whether the index value you specified in AlternativeIndex is for the list of alternatives in the Alternatives.InContext field or the Alternatives.OutContext field.
    • SessionId—Keep this value the same.
    Note: The values in the other input fields are ignored.
  15. Click Run Preview again. The value you specified will now be in the Field.n.Value field for the appropriate address element.
  16. Repeat the search and commit steps as often as needed until you have built the address.
  17. Close the session by entering the following values in the input fields:
    • Action—Type close.
    • SessionId—Keep this value the same.
    Note: The values in the other input fields are ignored.