Location data and address verification in the SPF API

The SPF API leverages an address normalization and geolocation service to determine precise employee work and home address locations within the United States. After passing in an employee’s home and work address, Symmetry determines the latitude and longitude of employee’s home and work addresses, normalizing the addresses in the process.

Demo

Below you can see an example address within the United States that is properly validated and normalized:

"locationData": [{
    "id": "home",
    "inputAddress": {
      "streetAddress1": "11 S Union St",
      "city": "Montgomery",
      "state": "AL",
      "zipCode": "36130"
    },
    "normalizedAddress": {
      "streetAddress1": "11 S Union St",
      "city": "Montgomery",
      "state": "AL",
      "zipCode": "36130-2102"
    },
    "addressResultMessages": {
      "GS01": {
        "message": "Geocoded to Street Level",
        "description": "The record was coded to the street level (Zip+4 for US, full postal code for CA)."
      },
      "AS01": {
        "message": "Valid Address",
        "description": "The address is valid and deliverable according to official postal agencies."
      }
    },
    "latitude": "32.376634",
    "longitude": "-86.299645",
    "geocoded": false,
    "verified": true
  },
  {
    "id": "work1",
    "inputAddress": {
      "streetAddress1": "64 N Union St",
      "city": "Montgomery",
      "state": "AL",
      "zipCode": "36130"
    },
    "normalizedAddress": {
      "streetAddress1": "64 N Union St",
      "city": "Montgomery",
      "state": "AL",
      "zipCode": "36130-3020"
    },
    "addressResultMessages": {
      "GS01": {
        "message": "Geocoded to Street Level",
        "description": "The record was coded to the street level (Zip+4 for US, full postal code for CA)."
      },
      "AS01": {
        "message": "Valid Address",
        "description": "The address is valid and deliverable according to official postal agencies."
      }
    },
    "latitude": "32.378229",
    "longitude": "-86.299726",
    "geocoded": false,
    "verified": true
  }
]

Address Verification not supported for CanadaPlease note that at this time, address verification is only available in the United States implementation of SPF.

Location Data Codes

As seen in the above response, we have provided an object called addressResultMessages. If an address is able to be validated it will always return with the addressResultMessages object, otherwise, if it fails, it will return with an addressErrorMessages object. Both of these objects will always contain a location data code, message, and description of what errors were encountered. GS01 and AS01 are examples of location data codes. See SPF address result codes for the full list of codes.

Major Result Code Category Prefixes

*AS - Address Status
The general address status, whether it is a valid address, US or foreign address, has moved, etc. *AE - Address Error
The address has caused an error with our data provider. Postal code doesn’t exist, issues with street provided, insufficient data provided, etc. *AC - Address Change
The address you provided has been changed or normalized. This could include corrections to zip code, city name, address, etc. *GS - Geocode Status
If an address was able to be geocoded this code specifies the level of accuracy. GS05 is the optimal geocoding accuracy status. *GE - Geocode Error
Specifies the reason(s) why an address has failed geocoding. This could be due to an invalid postal code, etc.

All Location Data CodesAll of our location data codes, messages, and descriptions are documented for current clients in the Client Support Center here.

Invalid Addresses

PO Boxes and Private MailboxesPost office boxes (PO boxes) and private mailboxes (PMB) are not valid addresses for Symmetry Payroll Forms. The physical location of a PO box or PMB does not represent the actual location where an employee lives or works.

Non-U.S. and Canadian AddressesNon-U.S. and Canadian addresses are currently not supported in Symmetry Payroll Forms.

Below is an example of a request and response of an invalid address.

{
	"homeAddress": {
	    "streetAddress1": "11 S Union St",
		"city": "Montgomery",
		"state": "AL",
		"zipCode": "36130"
	},
	"workAddresses": [
		{
			"streetAddress1": "64 N Union St",
			"city": "Montgomery",
			"state": "AZ",
			"zipCode": "12312"
		}
	]
}

As you can see above, the work address entered does not exist. The error response will be generated below:

{
            "id": "work1",
            "inputAddress": {
                "streetAddress1": "64 N Union St",
                "city": "Montgomery",
                "state": "AZ",
                "zipCode": "12312"
            },
            "normalizedAddress": {},
            "addressErrorMessages": {
                "AE01": {
                    "message": "Postal Code Error/General Error",
                    "description": "The address could not be verified at least up to the postal code level."
                }
            },
            "latitude": "",
            "longitude": "",
            "geocoded": false,
            "verified": false
        }

Pennsylvania Addresses and PSD Codes

For certain Pennsylvania forms, the SPF API will return PSD codes and additional information for valid addresses.

"locationData": [{
    "id": "home",
    "inputAddress": {
      "streetAddress1": "10 N 2nd St",
      "streetAddress2": "#1",
      "city": "Harrisburg",
      "state": "PA",
      "zipCode": "17101"
    },
    "normalizedAddress": {
      "streetAddress1": "10 N 2nd St, # 1",
      "city": "Harrisburg",
      "state": "PA",
      "zipCode": "17101-1677"
    },
    "addressResultMessages": {
      "GS05": {
        "message": "Geocoded to Rooftop Level",
        "description": "The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center."
      },
      "AS17": {
        "message": "No USPS Mail Delivery",
        "description": "US Only. The address is classified as not receiving mail by the USPS. This may be deliverable by third party delivery companies."
      },
      "AS02": {
        "message": "Street Only Match",
        "description": "The street address was verified but the suite/apartment number is missing or invalid."
      }
    },
    "latitude": "40.259594",
    "longitude": "-76.882629",
    "homePsdCode": "220401",
    "homePsdRate": "2.000000",
    "homePsdMunicipality": "Harrisburg, City of",
    "homePsdCounty": "Dauphin",
    "geocoded": true,
    "verified": true
  },
  {
    "id": "work1",
    "inputAddress": {
      "streetAddress1": "1400 John F Kennedy Blvd",
      "city": "Philadelphia",
      "state": "PA",
      "zipCode": "19107"
    },
    "normalizedAddress": {
      "streetAddress1": "1400 John F Kennedy Blvd",
      "city": "Philadelphia",
      "state": "PA",
      "zipCode": "19107-3200"
    },
    "addressResultMessages": {
      "GS05": {
        "message": "Geocoded to Rooftop Level",
        "description": "The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center."
      },
      "AS17": {
        "message": "No USPS Mail Delivery",
        "description": "US Only. The address is classified as not receiving mail by the USPS. This may be deliverable by third party delivery companies."
      },
      "AS02": {
        "message": "Street Only Match",
        "description": "The street address was verified but the suite/apartment number is missing or invalid."
      }
    },
    "latitude": "39.9533",
    "longitude": "-75.164",
    "workPsdCode": "510101",
    "workPsdRate": "3.501900",
    "workPsdMunicipality": "Philadelphia",
    "workPsdCounty": "Philadelphia",
    "geocoded": true,
    "verified": true
  }
]

In the above response, you will note some additional attributes for the Location Data object. These are listed below. If the address is a home address:
homePsdCode
homePsdRate
homePsdMunicipality
homePsdCounty If the address is a work address:
workPsdCode
workPsdRate
workPsdMunicipality
workPsdCounty This additional information will only populate for valid Pennsylvania addresses and should be used as values/answers to questions for certain local Pennsylvania forms, where the question ID matches the location data field. For example, QS1 for the form PA114 contains questions for the homePsdCode and homePsdRate.

Ohio Addresses and School District Information

For certain Ohio forms, specific school district information is required.

"locationData": [{
    "id": "home",
    "inputAddress": {
      "streetAddress1": "601 Lakeside Ave E",
      "city": "Cleveland",
      "state": "OH",
      "zipCode": "44114"
    },
    "normalizedAddress": {
      "streetAddress1": "601 Lakeside Ave E",
      "city": "Cleveland",
      "state": "OH",
      "zipCode": "44114-1027"
    },
    "addressResultMessages": {
      "GS05": {
        "message": "Geocoded to Rooftop Level",
        "description": "The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center."
      },
      "AS17": {
        "message": "No USPS Mail Delivery",
        "description": "US Only. The address is classified as not receiving mail by the USPS. This may be deliverable by third party delivery companies."
      },
      "AS02": {
        "message": "Street Only Match",
        "description": "The street address was verified but the suite/apartment number is missing or invalid."
      }
    },
    "latitude": "41.505134",
    "longitude": "-81.693663",
    "homeSchoolDistrictName": "Cleveland Municipal CSD ",
    "homeSchoolDistrictCode": "1809",
    "verified": true,
    "geocoded": true
  },
  {
    "id": "work1",
    "inputAddress": {
      "streetAddress1": "166 S High St",
      "city": "Akron",
      "state": "OH",
      "zipCode": "44308"
    },
    "normalizedAddress": {
      "streetAddress1": "166 S High St",
      "city": "Akron",
      "state": "OH",
      "zipCode": "44308-1626"
    },
    "addressResultMessages": {
      "GS05": {
        "message": "Geocoded to Rooftop Level",
        "description": "The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center."
      },
      "AS17": {
        "message": "No USPS Mail Delivery",
        "description": "US Only. The address is classified as not receiving mail by the USPS. This may be deliverable by third party delivery companies."
      },
      "AS02": {
        "message": "Street Only Match",
        "description": "The street address was verified but the suite/apartment number is missing or invalid."
      }
    },
    "latitude": "41.080679",
    "longitude": "-81.518086",
    "workSchoolDistrictName": "Akron CSD",
    "workSchoolDistrictCode": "7701",
    "verified": true,
    "geocoded": true
  }
]

In the above response you will note some additional attributes for the Location Data object. These are listed below and apply to Ohio specific forms. If the address is a home address:
homeSchoolDistrictName
homeSchoolDistrictCode If the address is a work address:
workSchoolDistrictName
workSchoolDistrictCode

​Demo

​Location Data Codes

​Major Result Code Category Prefixes

​Invalid Addresses

​Pennsylvania Addresses and PSD Codes

​Ohio Addresses and School District Information

Demo

Location Data Codes

Major Result Code Category Prefixes

Invalid Addresses

Pennsylvania Addresses and PSD Codes

Ohio Addresses and School District Information