--- title: "Determines tax jurisdiction and tax codes of list of addresses" method: POST path: "/v1/geo-tax/address/batch" tags: ["GeoTAX"] --- # Determines tax jurisdiction and tax codes of list of addresses `POST /v1/geo-tax/address/batch` ## Request - Base URL: `https://api.cloud.precisely.com` - URL: `https://api.cloud.precisely.com/v1/geo-tax/address/batch` - Auth: one of: - HTTP bearer - API key in header `Authorization` This endpoint takes a list of input addresses and determines which tax jurisdiction they are located in, and which current tax codes apply. ## Headers - `X-Request-Id` string ## Request body - TaxRateBatchRequest: Batch Request for Addresses - `addresses` TaxRateAddress[], required: List of Addresses - `addressId` string: Address Id for the request - `addressLines` string[]: Requested address, based on the country's addressing standard. - `addressNumber` string: House or building number. - `admin1` string: The largest geographic area, typically a state or province. - `admin2` string: The secondary geographic area, typically a county or district. - `city` string: Specifies a city or town name of address - `neighborhood` string: Neighborhood name. - `postalCode` string: Main postal code. - `postalCodeExt` string: Secondary postal code, if one exists. For example, in the US, a ZIP+4 is 80125-8012. - `street` string: The name of the street. - `building` string: Building name or identifier. - `unit` string: Apartment or unit number. - `unitType` string: The type of unit, such as apartment, suite, or lot. - `preferences` Preferences: Preferences - `geocoding` GeocodingPreference: Geocoding Preferences - `defaultBufferWidth` number, double: Set an alternative default buffer width. It must be positive integer/double value. - `userBoundaryBufferDistance` number, double: Set user boundary file buffer distance as integer value. It must be positive integer/double value. - `latLongOffset` '20' | '40' | '60' | 'NONE', required: Specifies the offset distance in feet from the latLong point. - `squeeze` 'YES' | 'NO', required: Specifies if the street end points should be squeezed when determining the geocode of an address in street-level matching. When Squeeze is enabled, both street and end points are moved closer to the center of the segment by 50 feet. - `latLongAltFormat` 'DecimalDirectional' | 'DecimalSign' | 'NoDecimalDirectional' | 'NoDecimalSign', required: Specifies another format for the latLong coordinates. - `usePointData` 'YES' | 'NO', required: Specifies to use MLD data or not. - `matching` MatchingPreference: Matching Preferences - `matchMode` 'CLOSE' | 'EXACT' | 'RELAXED', required: Match modes determines the leniency used to make a match between your input and the reference database. - `useGeoTaxAuxiliaryFile` 'YES' | 'NO', required: Specifies to use the GeoTAX auxiliary dataset or not. - `useUserAuxiliaryFile` 'YES' | 'NO', required: Specifies to use the user auxiliary dataset or not. - `output` OutputPreference: Output Preference - `taxDistrict` 'SPD' | 'IPD' | 'PAY' | 'NONE', required: Specifies the type of tax district information returned. - `salesTaxRateType` 'GENERAL' | 'AUTOMOTIVE' | 'CONSTRUCTION' | 'MEDICAL' | 'NONE', required: Specifies the sales and use tax rate type to return or none. - `outputCasing` 'UPPER' | 'MIXED', required: Specifies the casing of these output fields. - `taxCrossReferenceKey` 'NONE' | 'VERTEX' | 'TR' | 'SOVOS', required: Specifies to use cross reference data. - `usePTC` 'YES' | 'NO', required: Specifies o use the payroll tax correspondence dataset or not. - `userBoundary` 'YES' | 'NO', required: Specifies to use the user boundary dataset or not. ## Response `200` Tax Details Retrieved Successfully for batch addresses - TaxRateBatchResponse: Batch Response - `responses` TaxResponse[]: List of responses - `status` 'OK' | 'ZERO_RESULTS', required: Represents the status of a response - `errorMessage` string: Error message from the service. - `result` Result: Processed Result - `addressId` string: Address Id for the response - `gnisCode` string: Unique nine-digit Geographic Names Information System (GNIS) code. - `preciselyId` string: A unique address identifier that is returned when an address match is made using the Master Location Database. - `confidence` number, double: Indicates the confidence in the output provided; from 0 to 100. The higher the score, the higher the confidence in the match. - `jurisdiction` TaxJurisdiction: Tax Jurisdiction - `state` TaxState: Tax State - `code` string: Two-digit Federal Information Processing Standards (FIPS) state code extracted from the Census.BlockCode. - `name` string: Two-character state abbreviation. - `county` TaxCounty: Tax County - `code` string: Extracted from the Census.BlockCode. - `name` string: Name of the county. - `place` TaxPlace: Tax Place - `name` string: The name of the "place" where the address is located. - `code` string: Five-digit Federal Information Processing Standards (FIPS) place code. - `gnisCode` string: GNIS Code - `selfCollected` boolean: Self Collected - `classCode` string: Place class code. Place class codes are used to determine the proper taxing jurisdictions. - `incorporatedFlag` string: Indicates whether the address is located in an incorporated or unincorporated place. - `lastAnnexedDate` string: Last annexed date, in the format MM/YYYY, representing the month and year of the most recent boundary change or the most recent available boundary information. - `lastUpdatedDate` string: Last updated date, in the format MM/YYYY, reflecting the month and year when TomTom updated the database to reflect attribute (name change, FIPS change, etc.) or boundary edits to the Place. - `lastVerifiedDate` string: Last verified date, in the format MM/YYYY, representing the month and year that TomTom verified municipality change information. - `pointStatus` string: Returns the result for a comparison between the matched address point to the polygon defined by the Place.txb file. - `distanceToBorder` string: Returns the distance between the matched address point to the polygon defined by the Place.txb file. - `confidence` string: Provides the percentage overlap of the geocode to the Place polygon layer. - `geoTaxKey` string: The value in this field varies depending on the option you specified in the Sales tax cross-reference key option. - `geoTaxKeyMatchCode` string: Return code denoting the level of match obtained against the Vertex or Sovos cross reference files. - `spds` SpecialPurposeDistrict[]: List of SPDs - `stateId` string: SPD district id. - `districtName` string: SPD name. - `districtCode` string: 3-digit district type code. - `districtNumber` string: District number for SPD - `versionDate` string: SPD version date. - `effectiveDate` string: SPD effective date. - `compiledDate` string: SPD compiled date. - `updateDate` string: SPD update date. - `boundaryBuffer` BoundaryBuffer: Boundary Buffer - `bufferRelation` BufferRelation: Buffer Relation - … - `distanceToBorder` DistanceToBorder: Indicates the distance from the address to the border of the district. - … - `matchedAddress` MatchedAddress: Matched Address details for a request - `formattedAddress` string: All components of the address, formatted to the country's standard, on one line. - `formattedStreetAddress` string: Street portion of the address, including the directional and street suffix, formatted to the country's standard. - `formattedLocationAddress` string: The complete matched last address line (city, state, and postal code). - `addressNumber` string: House or building number. - `stateName` string: Street name. - `countyName` string: County name. - `cityName` string: Specifies a city or town name. - `postalCode` string: The matched address five-digit ZIP Code. - `postalCodeExt` string: The matched address four-digit ZIP Code extension. - `placeName` string: If applicable, indicates the name of the candidate's place or building. - `unit` string: Apartment number. For example, 123 E Main St APT 3. - `unitType` string: The type of unit, such as apartment, suite, or lot. - `street` string: The name of the street, not including any directionals or suffixes. - `firmName` string: The name of the business if the address is a business address. - `dataTypeName` string: Indicates the file from which the match was obtained. - `genRC` string: General Return Code indicating the type of match. - `locationCode` string: The Location Code indicates the methodology used to complete the geocode and may also provide some information about the quality of the geocode. - `matchCode` string: The Match Code indicates the portions of the address that matched or did not match to the reference file. - `numCandidates` string: When there are multiple equally-scored matches, returns the number of multiple match candidates found. - `urbanization` string: Urbanization name. Used for addresses in Puerto Rico. - `houseNumber` string: Building number for the address. - `preDirectional` string: Leading directional. For example, 123 E Main St Apt 3. - `streetType` string: The street type of the matched location. For example, AVE for Avenue. - `postDirectional` string: Street directional that follows the street name. For example, the "N" in this address: 456 Washington N. - `country` string: Country of the address - `city` string: City of the address - `salesTax` SalesTax: Sales Tax - `totalTaxRate` number, double: The sum of the individual Municipal, County, State and SPD sales tax rates. - `stateTaxRate` number, double: State sales tax rate for the selected tax rate type. - `countyTaxRate` number, double: County sales tax rate for the selected tax rate type. - `municipalTaxRate` number, double: Municipality sales tax rate for the selected tax rate type. - `resultCode` string: Tax Rate return code denoting the level of match obtained against the Precisely Sales and Use Tax Rate file. - `spdsTax` SpecialPurposeDistrictTax[]: List of SPDs - `districtNumber` string: SPD district number. - `taxRate` number, double: Tax rate for up to 10 Special Purpose Districts (SPD). - `useTax` UseTax: Use Tax - `totalTaxRate` number, double: The sum of the individual Municipal, County, State and SPD use tax rates. - `stateTaxRate` number, double: State use tax rate for the selected tax rate type. - `countyTaxRate` number, double: County use tax rate for the selected tax rate type. - `municipalTaxRate` number, double: Municipality use tax rate for the selected tax rate type. - `resultCode` string: Tax Rate return code denoting the level of match obtained against the Precisely Sales and Use Tax Rate file - `spdsTax` SpecialPurposeDistrictTax[]: Special Puropse District Tax List - `districtNumber` string: SPD district number. - `taxRate` number, double: Tax rate for up to 10 Special Purpose Districts (SPD). - `census` Census: Census - `block` string: Census Block ID. - `blockCode` string: A 15-digit census block ID/census FIPS code. - `blockGroup` string: Census Block Group code. - `cbsa` Cbsa: Core Based Statistical Area - `name` string: Name. - `code` string: Code. - `metroFlag` string: Indicates if the CBSA is a Metropolitan Statistical Area or a Micropolitan Statistical Area. - `matchLevel` string: The level of match obtained against the databases. - `matchCode` string: The code assigned to a specific level of match obtained against the databases. - `tract` string: Six-digit tract number extracted from the Census.BlockCode. - `mcd` Mcd: Minor Civil Division - `name` string: Minor Civil Division/Census County Division (MCD/CCD) name. - `code` string: Minor Civil Division/Census County Division (MCD/CCD) Code. - `pointStatus` string: The result for a comparison between the matched address point to the polygon defined by the Cousub.txb file. - `distanceToBorder` string: Returns the distance in feet between the matched address point to the polygon defined by the Cousub.txb file. - `confidence` string: Provides the percentage overlap of the geocode to the MCD polygon layer. - `cbsad` Cbsad: Core Based Statistical Area Division - `name` string: Name - `code` string: Code - `csa` Csa: Combined Statistical Area - `name` string: Csa Name - `code` string: Csa Code - `latLongFields` LatLongFields: Returned latitude/longitude, in the format you specified (up to 22 alphanumeric characters). - `matchCode` string: Latitude/Longitude General Return Code. Denotes the level for which the geocode was determined. - `matchLevel` string: A description of the value returned in the LatLong.MatchCode field. - `geometry` Geometry: Geometry - `latLongAltFmt` string: Latitude Longitude Alt Format - `latLongAltFmtValue` string: Returned latitude/longitude, in the format specified (up to 22 alphanumeric characters). - `type` string: type - `coordinates` number[]: Seven-digit numbers in degrees and calculated to four decimal places (in the format specified). - `numTaxDistrictsFound` integer: The number of Insurance Premium Tax Districts found for the location. - `ipds` Ipd[]: List of IPDs - `districtID` string: IPD ID. - `districtName` string: IPD name. - `districtType` DistrictType: District Type - `description` string: description of District Type - `value` string: value of District Type - `taxCodeDescription` string: Tax Code Description - `notes` string: Tax code descriptions. For example: 01, 33, A, B. - `effectiveDate` string: MMDDYY - Identifies when district becomes active - State supplied For example: 010108 - `expirationDate` string: MMDDYY - Identifies when district becomes inactive - State supplied For example: 063009 - `versionDate` string: IPD compiled date (MMYYYY). - `updateDate` string: IPD update date (MMYYYY). - `changeDate` string: IPD change date. - `boundaryBuffer` BoundaryBuffer: Boundary Buffer - `bufferRelation` BufferRelation: Buffer Relation - `description` string: Buffer Relation Description - `value` string: Indicates where in the district the location resides in relation to the edge of the district. - `distanceToBorder` DistanceToBorder: Indicates the distance from the address to the border of the district. - `unit` string: Unit - `value` string: Indicates the distance in feet from the address to the border of the district. - `rates` Rate[]: List of Rates - `name` string: Rate Name - `format` string: P - Percentage; .1 = 10%, .0575 = 5.75% F - Flat Fee dollar amount M - Multiple Percentages has a semi colon as a delimiter. 3;7 = "3% or 7%" - `formatDescription` string: Format Description - `value` string: Format is dependent on associated flag For example: .13, 15.00 or 3;7 - `ptds` PayrollTaxDistrict[]: Tax districts of a Payroll - `id` string: PAY ID. - `districtId` string: PAY district ID. - `districtName` string: PAY district name. - `districtType` string: PAY district type. - `updateDate` string: PAY update date. - `municipalEMSTax` string: PAY municipality emergency municipal services tax. The values for Pennsylvania are: Y Levies the tax N Does not levy the tax All other states are null. - `municipalIncomeTax` string: PAY municipality income tax. The values for Pennsylvania are: R Resident N Non-resident B Both X None All other states are null. - `schoolDistrictEMSTax` string: PAY school district emergency municipal services tax. The Values for Pennsylvania are: Y Levies the tax N Does not levy the tax All other states are null. - `schoolDistrictIncomeTax` string: PAY school district income tax. The values for Pennsylvania are: R Resident N Non-resident B Both X N The values for Ohio are: R Resident X None All other states are null. - `boundaryBuffer` BoundaryBuffer: Boundary Buffer - `bufferRelation` BufferRelation: Buffer Relation - `description` string: Buffer Relation Description - `value` string: Indicates where in the district the location resides in relation to the edge of the district. - `distanceToBorder` DistanceToBorder: Indicates the distance from the address to the border of the district. - `unit` string: Unit - `value` string: Indicates the distance in feet from the address to the border of the district. - `ptc` PayrollTaxCorrespondence: PayrollTaxCorrespondence - `matchCode` string: Indicates the level of match obtained for the address. - `ptcs` Ptc[]: List of Payroll Tax Correspondence - `payrollCode` string: A code that represents a taxing authority in a payroll application. - `payrollDescription` string: A description of the purpose of this payroll code. - `payrollFlag` string: A user-defined flag from the PTC database. - `userBoundaries` UserBoundary[]: List of User Boundaries - `boundaryID` string: The ID of the polygon as specified in the user-defined boundary file. - `boundaryDescription` string: A description of the polygon. - `supplementalBoundaryID` string: A supplemental ID as specified in the user-defined boundary file. - `boundaryConfidence` string: Provides the percentage overlap of the geocode to the User-defined boundary polygon layer. - `bufferRelation` string: Indicates where in the polygon the address resides in relation to the edge of the area. - `distanceToBorder` string: Indicates the distance from the address to the border of the polygon. The distance is in the units specified by the option Distance Units . ## Other responses - `400`: Invalid request for GeoTAX by batch address API - `401`: Unauthorized: Invalid token for GeoTAX by batch address API - `403`: Forbidden for GeoTAX by batch address API - `408`: Request timed out for GeoTAX by batch address API - `429`: Too many requests for GeoTAX by batch address API - `500`: Internal server error for GeoTAX by batch address API - `503`: Service unavailable for GeoTAX by batch address API --- [API](https://skmtc.dev/precisely/apis/geotax-api.md) · [All operations](https://skmtc.dev/precisely/apis/geotax-api/llms.txt) · [OpenAPI document](https://skmtc.dev/precisely/apis/geotax-api/revisions/b70a948f8d0c?raw)