II.4 One-Work-Area and Two-Work-Area Calls

There are important distinctions between one-work-area and two-work-area calls. When a Geosupport function is called using one work area, Geosupport ‘normalizes’ certain input items, that is, it reformats them into a standard form.  For each such input item that Geosupport successfully normalizes, there is a WA1 output field into which Geosupport inserts the item in normalized form.  Normalizing includes such processing as right-justifying and zero-filling certain numeric input items (such as tax block and tax lot numbers), and providing fully spelled out borough names corresponding to input borough codes. Normalizing also encompasses performing complex algorithms to reformat street names and address numbers into standard formats.

After normalizing the appropriate input items, if the one-work-area call involves street name input items, Geosupport attempts to retrieve the street code corresponding to each input street name. If this is successful, each street code is returned in WA1. In summary, the processing Geosupport performs for a one-work-area call consists of normalization of the input data and the return of normalized values and street codes (if any) in WA1. 

The processing performed for a two-work-area call includes all of the processing performed for a one-work-area call as well as certain additional processing.  The nature of this additional processing depends on the Geosupport function. The additional processing generally consists of accessing Geosupport files in order to attempt to obtain certain geographic information associated with the input data.  If the file access is successful, this geographic information is returned in WA2 (but see the cautionary note below).  The process of associating higher level geographic information with an individual location is called geocoding, and the items of higher level information are called geocodes.  Typical examples of geocodes returned by Geosupport in WA2 are community district, census tract, ZIP code and health area.

Caution: For a two-work-area call, a GRC of ‘00’ or ‘01’ signifies that Geosupport has accepted as valid the input geographic location specified by the user, but it does not guarantee that every item normally returned by the given function in WA2 contains a non-empty value.  If a WA2 field is returned empty, this may or may not be erroneous. The field might be empty (blanks, zeros or otherwise devoid of information) because of an erroneous Geosupport data omission; this should be reported to GSS staff using the feedback procedures described in Appendix 6.  However, the field might be empty intentionally and non-erroneously because the type of geographic area it represents does not completely cover the city. For example, there are certain non-residential areas of the city where the Department of Sanitation has not defined Collection Scheduling districts. When a two-work-area call results in a GRC of ‘00’ or ‘01’, it is the responsibility of the user program to determine whether the particular WA2 fields being used by the application are non-empty.

Except for system errors, the outcome of a call to Geosupport, as signified by the GRC, Reason Code and Message, concomitantly has significance with respect to the geographic validity of the input data. The type of validation performed depends on the function and on whether a one- or two-work-area call has been made. The validations performed in a two‑work‑area call to a function are always more extensive than those performed in a one-work-area call to the same function.  To illustrate this, consider Function 2, which processes an intersection specified in terms of two streets (note that Function 2 can also process intersections based on an intersection name or a node ID, but those inputs are not relevant to this example).  In a one-work-area Function 2 call, if the two input streets were specified in the form of street names rather than street codes, Geosupport attempts to normalize the street names and obtain their street codes; success in doing so therefore validates that each input street name is recognizable to Geosupport as a valid name of a specific New York City street.  However, the two input streets (names or codes) are processed independently of each other and are not treated as collectively defining a geographic location, in this case an intersection. In other words, when Function 2 is called using one work area, the existence of the intersection formed by the two input streets is not validated; the call will result in a GRC of ‘00’ or ‘01’ if both input street names are successfully normalized and recognized, regardless of whether the two streets intersect.  In a two-work-area Function 2 call, on the other hand, Geosupport treats the two input streets as the intended specification of an intersection; an (unconditionally or conditionally) successful outcome validates the existence of this intersection, and if it is valid, Geosupport returns information about the intersection in WA2. For Geosupport functions in general, a one-work-area call validates only that the input items can be normalized and that input street names are recognizable to Geosupport, while a two-work-area call additionally provides some level of validation of the geographic location specified collectively by the input items. The specific validations performed in a two-work-area call to each Geosupport function are described in Chapters V through VII.

A two‑work‑area call causes Geosupport to access files additional to those accessed for a one‑work‑area call to the same function. Therefore, to maximize execution efficiency, when an application does not require the additional output data and/or validation processing that a two‑work‑area call provides, the application should issue a one-work-area call.