# Obtain PCodes

Source: https://developer.avalara.com/products/communications/integration-guides/communications-integration/ofo2877172603346/

Guide: Communications

# Obtain PCodes

Use the [GetPCode](https://developer.avalara.com/api-reference/communications/v2/methods/Jurisdiction%20Determination/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. Passing`0` 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
}
```