Auxiliary File Layout

You must comply with the following organizational rules when you create auxiliary file:

  • Files are fixed-width text files with a .gax extension
  • Files can contain up to 500,000 records.
  • Use semicolons in the first column to indicate a row is a comment, not a data record; GeocodeUSAddress ignores rows that begin with a semicolon.
  • For optimal performance, order the records within the file by descending ZIP Code, and then descending street name.
  • Records must represent only one side of a street. To represent both sides of a street, create a record for each side of the street.
  • Records must represent segments that are straight lines.
  • House numbers must follow USPS rules documented in Publication 28.
  • Numeric fields, such as ZIP Codes, must contain only numbers.
  • If house numbers are present in the record, the house number range must be valid according to USPS rules documented in Publication 28, Appendix E.
  • Latitude and Longitude values must be in millionths of decimal degrees.
  • Records cannot contain PO Box addresses.

The following table shows auxiliary file layout.

Field

Description

Required

Required for Street Segment Match

Required for Landmark Match

Exact Match Required if Present

Length

Position

ZIP Code

5-digit ZIP Code.

X

X

X

X

5

1-5

Street name

Name of the street or landmark.

X

X

X

X

30

6-35

Street type abbreviation

Street type. Also called street suffix.

See the USPS Publication 28, Appendix C for a complete list of supported street types.

X

4

36-39

Predirectional

USPS street name predirectional abbreviation. Supported values are N, E, S, W, NE, NW, SE, and SW.

X

2

40-41

Postdirectional

USPS street name postdirectional abbreviations. Supported values are N, E, S, W, NE, NW, SE, and SW.

X

2

42-43

RESERVED

RESERVED

4

44-47

Low house number

Low house number of the address range.

X

X

11

48-58

High house number

High house number of the address range.

X

X

11

59-69

House number parity

Indicates the parity of the house number in the range.

E - Even

O - Odd

B - Both

1

70

Segment direction

Direction the house numbers progress along the segment:

F - Forward (default)

R - Reverse

1

71

RESERVED

RESERVED

1

72

FIPS state

US government FIPS state code.

2

73-74

FIPS county

US government FIPS county code.

3

75-77

Census tract

US Census tract number.

6

78-83

Census block group

US Census block group number.

1

84

Census block ID

US Census block ID number.

3

85-87

RESERVED

RESERVED

5

88-92

State abbreviation

USPS state abbreviation.

2

93-94

County name

Name of the county.

25

95-119

MCD code

Minor Civil Division code.

5

120-124

MCD name

Minor Civil Division name.

40

125-164

CBSA code

Core Based Statistical Area code.

5

165-169

CBSA name

Core Based Statistical Area name.

49

170-218

RESERVED

RESERVED

5

219-223

City Name

City name. Overrides the city/state preferred city name upon a return.

40

224-263

RESERVED

RESERVED

237

264-500

User-defined data

User-defined data.

300

501-800

Record ID Number

User-defined unique record identifier.

10

801-810

Side of street

Side of the street for the address:

L - Left side

R - Right side

B - Both sides

U - Unknown side (default)

This is relative to the segment endpoints and the segment direction.

1

811

Beginning longitude

Beginning longitude of the street segment in millionths of degrees.

X

X

X

11

812-822

Beginning latitude

Beginning latitude of the street segment in millionths of degrees.

X

X

X

10

823-832

Ending longitude

Ending longitude of the street segment in millionths of degrees.

11

833-843

Ending latitude

Ending latitude of the street segment in millionths of degrees.

10

844-853