Avalara Developer Network Developer communications

Chapter 4.4.1 - PCode Jurisdiction Determination

The /api/v2/afc/PCode Jurisdiction Determination endpoint returns a list of PCodes associated with a specified location.

PCode Jurisdiction Determination

The PCode Jurisdiction Determination endpoint accepts a Zip Lookup Request. Specify a location, best match or exact match, and how many results you want to see. Location data, including PCode, is returned along with additional details in the Zip Lookup Result .

Location Data

Specify a location.

  • Include least one of the location fields:
    • Country (CountryISO)
    • State (State)
    • County (County)
    • City (City)
    • Postal Code (ZipCode)
  • Country defaults to "USA" if not supplied


Best Match

The Best Match flag (BestMatch) indicates the type of results.

  • true: Best match is returned
    • An exact match is attempted first
    • Best Match is applied if the exact match search fails
  • false: Only an exact match is returned
  • Check the MatchTypeApplied Zip Lookup Result field to see which match type is used


Considerations when using the Best Match flag:

  • Punctuation in a city names is ignored
  • Whitespace in a city name is ignored
  • For example, the city name "LAND O' LAKES" is returned as an exact match when "LAND O LAKES" or "LANDOLAKES" are supplied because both punctuation and white space is ignored


Limit Results

The Limit Results field (LimitResults) is used to limit the number of matches returned in the Zip Lookup Result.

  • Default is 100 results - passing 0 sets the limit to the default
  • Maximum is 1,000 results - passing a value greater than the max sets the limit to the maximum

PCode Jurisdiction Determination Example 1 - Best Match

This example demonstrates a best match PCode Jurisdiction Determination request.

{
  "CountryIso": "USA",
  "State": "MN",
  "County": "SAINT LOUIS",
  "City": "EVELETH",
  "ZipCode": "55734",
  "BestMatch": true,
  "LimitResults": 10
}

Response

One location (LocationData) is returned using a best match (MatchTypeApplied).

View the Response JSON
{
  "LocationData": [
    {
      "CountryIso": "USA",
      "State": "MN",
      "County": "ST LOUIS",
      "Locality": "EVELETH",
      "PCode": 1956600
    }
  ],
  "MatchCount": 1,
  "InputMatchType": "Best",
  "MatchTypeApplied": "Best",
  "ResultsLimit": 10
}

PCode Jurisdiction Determination Example 2 - Zip Code

This example demonstrates a best match request using only a zip code (ZipCode).

{
  "ZipCode": "10001",
  "BestMatch": true,
  "LimitResults": 25
}

Response

Five locations (LocationData) are returned using an exact match (MatchTypeApplied).

View the Response JSON
{
  "LocationData": [
    {
      "IsAlternate": true,
      "CountryIso": "USA",
      "State": "NY",
      "County": "NEW YORK",
      "Locality": "EMPIRE STATE",
      "PCode": 2604100
    },
    {
      "IsAlternate": true,
      "CountryIso": "USA",
      "State": "NY",
      "County": "NEW YORK",
      "Locality": "GREELEY SQUARE",
      "PCode": 2604100
    },
    {
      "IsAlternate": true,
      "CountryIso": "USA",
      "State": "NY",
      "County": "NEW YORK",
      "Locality": "ONE HUNDRED THIRTY EIGHTH",
      "PCode": 2604100
    },
    {
      "IsAlternate": true,
      "CountryIso": "USA",
      "State": "NY",
      "County": "NEW YORK",
      "Locality": "MANHATTAN",
      "PCode": 2604100
    },
    {
      "CountryIso": "USA",
      "State": "NY",
      "County": "NEW YORK",
      "Locality": "NEW YORK",
      "PCode": 2604100
    }
  ],
  "MatchCount": 5,
  "InputMatchType": "Best",
  "MatchTypeApplied": "Exact",
  "ResultsLimit": 25
}

PCode Jurisdiction Determination Example 3 - India Best Match

This example demonstrates a PCode lookup in India (CountryISO is set to “IND”).

{
  "CountryIso": "IND",
  "State": "AP",
  "City": "Tirumala",
  "BestMatch": true,
  "LimitResults": 1
}

Response

The country of India (CountyISO) is returned even though a local jurisdiction is requested.

View the Response JSON
{
  "LocationData": [
    {
      "CountryIso": "IND",
      "State": "",
      "County": "",
      "Locality": "",
      "PCode": 5148400
    }
  ],
  "MatchCount": 1,
  "InputMatchType": "Best",
  "MatchTypeApplied": "Best",
  "ResultsLimit": 1
}

PCode Jurisdiction Determination Example 4 - India Exact Match

Similar to Example 3, but with an exact match requested (BestMatch set to false).

{
  "CountryIso": "IND",
  "State": "AP",
  "City": "Tirumala",
  "BestMatch": false,
  "LimitResults": 1
}

Response

No results are returned because an exact match for the requested jurisdiction can’t be found.

View the Response JSON
{
  "LocationData": null,
  "MatchCount": 0,
  "InputMatchType": "Exact",
  "MatchTypeApplied": "Exact",
  "ResultsLimit": 1
}