API Documentation

Canadian Address Cleanse.

Validate and standardize a Canadian address in real time. The response tells you whether the address is deliverable, which fields were corrected, and parses the address into individual fields — including the FSA and LDU portions of the postal code.

Endpoint: https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse
Methods: GET for a single address · POST for a batch
Formats: JSON by default; append .xml for XML

Authentication

Every request carries your API key in the query string. The API is HTTPS-only, so the key is encrypted in transit. Query parameters can appear in any order, and responses are JSON by default — append .xml to the endpoint for XML.

https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse?apikey={apikey}&…

Don't have a key? Sign up under plans & pricing below — keys work immediately.

Request

Pass the address in one of two shapes — never both in the same request. Use the standard format when your data is already split into fields; use the multiline format when addresses arrive free-form.

Standard Canadian format

Parameter	Required	Description
apikey	Yes	Your unique API key.
address1	—	Street address portion. Example: 111 Main St.
address2	—	Secondary address, usually the suite or apartment number. Example: Suite 200.
city	—	City name. Don't combine with lastline. Example: Port Hope.
province	—	The province. Don't combine with lastline. Example: ON.
postalcode	—	The postal code. Don't combine with lastline. Example: L1A 3G3.
lastline	—	Use when city, province, and postal code arrive as one line. Example: Port Hope, ON L1A 3G3.

Multiline format

Parameter	Required	Description
apikey	Yes	Your unique API key.
line1 … line8	—	The address exactly as you have it, one field per line, up to eight lines. The cleanse works out which line is which.

Multiline requests need at least two address lines.

Examples

Single address (GET)

curl "https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse?apikey={apikey}\
&address1=111+Main+St\
&city=Port+Hope&province=ON&postalcode=L1A+3G3"

Batch (POST) — one JSON array, same fields per address

POST https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse?apikey={apikey}
Content-Type: application/json

[
  {
    "address1": "111 Main St",
    "city": "Port Hope",
    "province": "ON",
    "postalCode": "L1A 3G3"
  },
  { "...": "up to your plan's max addresses per request" }
]

Multiline (GET)

curl "https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse?apikey={apikey}\
&line1=111+Main+St\
&line2=Port+Hope%2C+ON+L1A+3G3"

Response shape (GET) — POST wraps these in a totals envelope, like the US cleanse

{
  "status": "",
  "statusMessage": "",
  "rawDetailCode": "",
  "requestId": "",
  "fullAddress": "",
  "primaryAddress": "",
  "secondaryAddress": "",
  "lastLine": "",
  "components": { "…": "see the components table" },
  "metadata": { "…": "see the metadata table" }
}

Response reference

Root fields

Field	Type	Description
status	String(36)	Result of the cleanse: Valid or Invalid.
statusMessage	String	When status is Invalid, the descriptive message.
rawDetailCode	String(6)	Positional processing code, same idea as the US cleanse — see quality codes below for the friendlier signal.
requestId	String(50)	Echo of the requestId you sent, unchanged.
fullAddress	String(256)	Single-line address containing the primary and secondary address.
primaryAddress	String(256)	Primary address line — street address or post office box, without secondary information.
secondaryAddress	String(64)	Building name, floor, and room number in one field.
lastLine	String(176)	City, province, and postal code.
components		Parsed address pieces — see the components table.
metadata		Delivery details — see the metadata table.

components

Field	Type	Description
city	String(128)	City preferred by the postal authority.
city13	String(13)	Abbreviated city preferred by the postal authority.
postalCode	String(20)	Full postal code, containing the FSA and LDU.
postalCodeFsa	String(10)	The FSA (forward sortation area) portion of the postal code — the first three characters.
postalCodeLdu	String(5)	The LDU (local delivery unit) portion of the postal code — the last three characters.
primaryNumber	String(64)	The premise number.
primaryPrefix	String(40)	Abbreviated directional (N, S, NW, SE…) before the street name.
primaryName	String(128)	Street name.
primaryType	String(40)	Abbreviated street type — St, Ave, Pl.
primaryPostfix	String(40)	Abbreviated directional (N, S, NW, SE…) after the street name.
province	String(128)	Province abbreviation.
secondaryUnitDescription	String(20)	Unit description — #, Apartment, Flat.
secondaryUnitNumber	String(12)	Unit number — the 100 in “APT 100”.
remainderFull	String(256)	All remainder information in one field.
extraLine1	String(128)	Non-address data found above or below the address. Multiline input only.
extraLine2	String(128)	Non-address data found above or below the address. Multiline input only.

metadata

Field	Type	Description
addressType	String(25)	Type of address. Street — standard street address HighRise — multi-unit building BuildingName — identified by building name Firm — business with its own record Postal — postal box Rural — rural address StreetServedByRoute — street address served by a route GeneralDelivery — general delivery Military — military address Unknown — couldn't be classified
deliveryInstallationName	String(30)	The delivery installation city name — usually the same as the city and omitted from the address line. When it differs from the locality name, it's output to the secondary address fields.
deliveryInstallationType	String(30)	The delivery installation type. PostOffice — post office RetailPostOutlet — retail post outlet Station — station LetterCarrierDepot — letter carrier depot CommunityMailCenter — community mail center CommercialDealershipOutlet — commercial dealership outlet
qualityCode	String(2)	Two-character code describing the quality of the address — see the quality codes section below.

Quality codes

The qualityCode field grades how confidently the address validated.

Code	Description
Q1	Perfect address on input. Every component validated without corrections.
Q2	Corrected address. Every component validated after corrections were made.
Q3	Not fully validated — insufficient information to make a final correction, but a high likelihood the address is deliverable.
Q4	Not fully validated — a fair likelihood the address is deliverable.
Q5	Not fully validated — a small likelihood the address is deliverable.
Q6	Not fully validated — highly unlikely the address is deliverable.

HTTP response codes

Code	Description
200	Processed successfully.
400	Bad request — the API key format is invalid, the key is missing, or the input wasn't properly passed.
401	Unauthorized — the API key is inactive or invalid.
403	Forbidden — the request exceeds the max items allowed per call, or the account isn't set up for this service.
408	Request timeout — processing exceeded the max processing time.
500	Internal server error during processing.

Plans & pricing

Canadian Address Cleanse is included in the Address Validation subscription — one plan covers this service, US Address Cleanse, and ZIP Code Information, all sharing the same API key and monthly pool of lookups.

Free

250 lookups per month

Hard limit of 250 lookups per month — perfect for evaluating.

$30/mo

1,000 lookups per month

$0.03 per lookup above 1,000 in a month.

$100/mo

10,000 lookups per month

$0.01 per lookup above 10,000 in a month.

$400/mo

50,000 lookups per month

$0.008 per lookup above 50,000 in a month.

$600/mo

100,000 lookups per month

$0.006 per lookup above 100,000 in a month.

$1,250/mo

250,000 lookups per month

$0.005 per lookup above 250,000 in a month.

Above 250,000 lookups a month, or if you'd rather be invoiced, talk to us — we'll set up a plan that fits.

Validating Canadian addresses?

Tell us what you're building and we'll get you moving — usually the same day.

Send Us a Note 678-987-4600