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 PCode 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 PCode 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)
    • NPANXX Code (NpaNxx)
    • Fips Code (Fips)
  • Country defaults to "USA" if not supplied
  • Use "*" at the end of NpaNxx and Fips to get a range of values

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
}

PCode Jurisdiction Determination Example 5 - NPANXX Range

This example demonstrates both an NPANXX and Fips code range by using a “*”.

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

Response

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 the Response JSON
{
  "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
}

See Also

Input Objects

Output Objects

PreviousNext