Location Data and Address Verification

The SPF API leverages an address normalization and geolocation service to determine precise employee work and home address locations.

After passing in an employees’ home and work addresses. Symmetry determines the latitude and longitude of employees’ home and work addresses, normalizing the addresses in the process.

Below you can see a sample of an address 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
  }
]

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.

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 Codes

All of our location data codes, messages, and descriptions come directly from Melissa Data. If you are looking for additional information about any of these codes or responses sent back check out their website!

http://wiki.melissadata.com/index.php?title=Result_Codes

Invalid Addresses

❗️

Submitting Invalid Addresses

Invalid addresses will not be validated through the Location Code Service. If an address is invalid and cannot be found, SPF-API will return an address error.

❗️

PO Boxes and Private Mailboxes

Post 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. Addresses

Non-U.S. 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 can even 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, it will be required to enter specific school district information.

"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


What’s Next
Jump to top