Obtain PCodes

Use the GetPCode endpoint to retrieve a list of PCodes for a specific jurisdiction. When running this endpoint, specify a location, best match or exact match, and how many results you want to see.

Location data must include at least one of the following fields:

Country (CountryISO)
State (State)
County (County)
City (City)
Postal Code (ZipCode)
NPANXX Code (NpaNxx)
Fips Code (Fips)

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 field in the result to see which match type is used.

When enabling the BestMatch flag, punctuation and white spaces in a city names are 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 are ignored.

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

By default,100 results are returned. Passing0 sets the limit to the default.
The maximum number of results is 1,000. Passing a value greater than this maximum sets the limit to the maximum.

Note

Once you use Avalara to derive the PCode from an address, you can rely on this value. (It will not change.) Be sure to revalidate addresses on a periodic basis to make sure the best jurisdiction boundary match is made to an address as boundaries can change over time.
For high volume clients using street-address-level geo coding, we make it a requirement to GeoPCode addresses prior to calculation.

Obtain PCodes examples

We have a few examples to demonstrate the sample request and response scenarios.

Example 1: Best match with an address

This example demonstrates a best match PCode Jurisdiction Determination request.

View request:

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

View response:

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

Example 2: Best match with a zip code

This example demonstrates a best match request using only a zip code (ZipCode). The response returns 5 locations (LocationData) using an exact match (MatchTypeApplied).

View request:

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

View response:

{
  "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
}

Example 3: Best match with country

This example demonstrates a PCode lookup in India (CountryISO is set to “IND”). The response returns the country of India (CountyISO), even though a local jurisdiction is requested.

View request:

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

View response:

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

Example 4: Exact match with country

This example is similar to Example 3, except that an exact match is requested (BestMatch is set to “False ”). No results are returned because an exact match for the requested jurisdiction can’t be found.

View request:

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

View response:

{
  "LocationData": null,
  "MatchCount": 0,
  "InputMatchType": "Exact",
  "MatchTypeApplied": "Exact",
  "ResultsLimit": 1
}

Example 5: NPANXX range

This example demonstrates both an NPANXX and Fips code range by using a wildcard (“*”). The results are limited to 14 jurisdictions:

1 jurisdiction returned for Johnson County, KS
12 jurisdictions related to the 816 NPANXX range
1 jurisdiction returned for the 9901250415 range

View request:

{
  "CountryIso": "USA",
  "State": "KS",
  "County": "Johnson",
  "NpaNxx": "816*",
  "Fips": "9901250415*",
  "LimitResults": 12
}

View response:

{
  "LocationData": [
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "",
      "Locality": "",
      "PCode": 2047400
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "LIVINGSTON",
      "Locality": "CHILLICOTHE",
      "PCode": 2119300
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "CASS",
      "Locality": "KANSAS CITY",
      "PCode": 2067600
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "BUCHANAN",
      "Locality": "SAINT JOSEPH",
      "PCode": 2058600
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "JOHNSON",
      "Locality": "WARRENSBURG",
      "PCode": 2109600
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "ADAIR",
      "Locality": "KIRKSVILLE",
      "PCode": 2047600
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "JACKSON",
      "Locality": "KANSAS CITY",
      "PCode": 2102300
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "CLAY",
      "Locality": "KANSAS CITY",
      "PCode": 2074600
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "PLATTE",
      "Locality": "KANSAS CITY",
      "PCode": 2149800
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "JACKSON",
      "Locality": "KANSAS CITY",
      "PCode": 2102300
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "PLATTE",
      "Locality": "KANSAS CITY",
      "PCode": 2149800
    },
    {
      "CountryIso": "USA",
      "State": "MO",
      "County": "BUCHANAN",
      "Locality": "SAINT JOSEPH",
      "PCode": 2058600
    },
    {
      "CountryIso": "USA",
      "State": "KS",
      "County": "JOHNSON",
      "Locality": "OVERLAND PARK",
      "PCode": 1248900
    },
    {
      "CountryIso": "USA",
      "State": "KS",
      "County": "JOHNSON",
      "Locality": "",
      "PCode": 1248000
    }
  ],
  "MatchCount": 13,
  "InputMatchType": "Best",
  "MatchTypeApplied": "Exact",
  "ResultsLimit": 12
}