https://docs.addresszen.com/assets/js/be543bcf.882bd17a.js

1"use strict";(globalThis.webpackChunk_atlas_docs_zen=globalThis.webpackChunk_atlas_docs_zen||[]).push([[7059],{1145(e,s,d){d.r(s),d.d(s,{assets:()=>o,contentTitle:()=>c,default:()=>h,frontMatter:()=>n,metadata:()=>r,toc:()=>l});const r=JSON.parse('{"id":"sdks/typescript/endpoints/find-address","title":"findAddress","description":"Find Address","source":"@site/docs/sdks/typescript/endpoints/find-address.mdx","sourceDirName":"sdks/typescript/endpoints","slug":"/sdks/typescript/endpoints/find-address","permalink":"/docs/sdks/typescript/endpoints/find-address","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{"id":"find-address","title":"findAddress"},"sidebar":"sdks","previous":{"title":"addressVerify","permalink":"/docs/sdks/typescript/endpoints/address-verify"},"next":{"title":"retrieveAddress","permalink":"/docs/sdks/typescript/endpoints/retrieve-address"}}');var t=d(5723),i=d(4056);const n={id:"find-address",title:"findAddress"},c="findAddress",o={},l=[{value:"Coverage",id:"coverage",level:2},{value:"Filters",id:"filters",level:2},{value:"Address bias",id:"address-bias",level:2},{value:"Suggestion format",id:"suggestion-format",level:2},{value:"Rate limiting and cost",id:"rate-limiting-and-cost",level:2},{value:"Endpoint",id:"endpoint",level:2},{value:"Import",id:"import",level:2},{value:"Path Parameters",id:"path-parameters",level:2},{value:"Query Parameters",id:"query-parameters",level:2},{value:"Response Type",id:"response-type",level:2},{value:"Errors",id:"errors",level:2},{value:"Example",id:"example",level:2}];function a(e){const s={a:"a",code:"code",em:"em",h1:"h1",h2:"h2",header:"header",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(s.header,{children:(0,t.jsx)(s.h1,{id:"findaddress",children:(0,t.jsx)(s.code,{children:"findAddress"})})}),"\n",(0,t.jsx)(s.p,{children:"Find Address"}),"\n",(0,t.jsx)(s.p,{children:"Returns address suggestions for a partial address, ranked by relevance. Use it to autofill an address form as the user types."}),"\n",(0,t.jsxs)(s.p,{children:["A suggestion is a display label and an ",(0,t.jsx)(s.code,{children:"id"}),", not a full address. Retrieve the address with a second request to ",(0,t.jsx)(s.code,{children:"/autocomplete/addresses/{id}/usa"}),". That second request is the one which decrements your lookup balance."]}),"\n",(0,t.jsx)(s.p,{children:"Autocomplete is not a free standalone resource. We rate limit, then suspend, keys that autocomplete without resolving suggestions."}),"\n",(0,t.jsx)(s.p,{children:"Our address autocomplete JavaScript libraries add this to a form without calling the API directly."}),"\n",(0,t.jsx)(s.h2,{id:"coverage",children:"Coverage"}),"\n",(0,t.jsxs)(s.p,{children:["Each search runs in one country, selected with ",(0,t.jsx)(s.code,{children:"context"}),". A missing or unrecognized ",(0,t.jsx)(s.code,{children:"context"})," falls back to your account default. Results come from the datasets enabled on your key: USPS Zip+4 for the US and its territories, and the country datasets you license elsewhere. Where a key has more than one dataset for a country, ",(0,t.jsx)(s.code,{children:"dataset"})," narrows the search."]}),"\n",(0,t.jsx)(s.h2,{id:"filters",children:"Filters"}),"\n",(0,t.jsxs)(s.p,{children:["Filters restrict results, e.g. ",(0,t.jsx)(s.code,{children:"state_code=NY"})," searches New York only. A filter which matches no address returns an empty set. An unrecognized filter name is ignored. Neither affects your lookup balance."]}),"\n",(0,t.jsxs)(s.p,{children:["Filters combine with ",(0,t.jsx)(s.code,{children:"AND"})," logic, so ",(0,t.jsx)(s.code,{children:"state_code=CA&city=San Francisco"})," requires both. A comma-separated value combines terms for one filter, e.g. ",(0,t.jsx)(s.code,{children:"postal_code_3=11225,11226,11238"})," accepts any of the three ZIP codes. Unless a parameter states otherwise, every filter takes multiple terms. The maximum is 10 filter terms."]}),"\n",(0,t.jsx)(s.h2,{id:"address-bias",children:"Address bias"}),"\n",(0,t.jsxs)(s.p,{children:["Bias terms carry the ",(0,t.jsx)(s.code,{children:"bias_"})," prefix and promote addresses rather than restricting the set, so unmatched addresses still appear, lower down. For example, ",(0,t.jsx)(s.code,{children:"bias_state_code=NY,NJ"})," favors addresses in New York and New Jersey, ",(0,t.jsx)(s.code,{children:"bias_lonlat"})," favors addresses near a point. Invalid bias terms have no effect. Multiple bi

1as terms are allowed unless stated otherwise, with a combined maximum of 5."]}),"\n",(0,t.jsx)(s.h2,{id:"suggestion-format",children:"Suggestion format"}),"\n",(0,t.jsx)(s.p,{children:"The suggestion string is subject to change. Present it to the user as it arrives rather than parsing it."}),"\n",(0,t.jsx)(s.h2,{id:"rate-limiting-and-cost",children:"Rate limiting and cost"}),"\n",(0,t.jsxs)(s.p,{children:["The default rate limit is 3,000 requests per 5 minutes, counted per API key and IP address. The ",(0,t.jsx)(s.code,{children:"X-RateLimit-Limit"}),", ",(0,t.jsx)(s.code,{children:"X-RateLimit-Remaining"})," and ",(0,t.jsx)(s.code,{children:"X-RateLimit-Reset"})," headers report the current window."]}),"\n",(0,t.jsx)(s.p,{children:"Autocomplete requests do not draw on your balance. Resolving a suggestion to a full address does."}),"\n",(0,t.jsx)(s.h2,{id:"endpoint",children:"Endpoint"}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.code,{children:"GET /autocomplete/addresses"})}),"\n",(0,t.jsxs)(s.p,{children:["See the ",(0,t.jsx)(s.a,{href:"/docs/api/find-address",children:"API reference"})," for this endpoint."]}),"\n",(0,t.jsx)(s.h2,{id:"import",children:"Import"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-ts",children:'import { findAddress } from "@addresszen/sdk";\n'})}),"\n",(0,t.jsx)(s.h2,{id:"path-parameters",children:"Path Parameters"}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.em,{children:"None."})}),"\n",(0,t.jsx)(s.h2,{id:"query-parameters",children:"Query Parameters"}),"\n",(0,t.jsxs)(s.table,{children:[(0,t.jsx)(s.thead,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.th,{children:"Name"}),(0,t.jsx)(s.th,{children:"Type"}),(0,t.jsx)(s.th,{children:"Required"}),(0,t.jsx)(s.th,{children:"Description"})]})}),(0,t.jsxs)(s.tbody,{children:[(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"api_key"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"API Key"})," Your unique identifier that allows access to our APIs. Begins ",(0,t.jsx)(s.code,{children:"ak_"}),". Available from your dashboard."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"query"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Address Query"})," The partial address string entered by the user to autocomplete."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"dataset"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"Array<Dataset>"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by Dataset"})," Comma-separated list of datasets to search within. Filters results to only include addresses from the specified datasets. Useful for keys with multiple overlapping datasets enabled (e.g. ",(0,t.jsx)(s.code,{children:"paf"})," and ",(0,t.jsx)(s.code,{children:"abp"}),")."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"context"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Context"})," Limits search results, typically within a country."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"limit"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"number"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Limit"})," Specifies the maximum number of records to retrieve. By default the limit is 10. Requesting a larger result set adds latency."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"bias_lonlat"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Bias by Geolocation"})," Bias search to a geospatial circle determined by an origin and radius in meters. Max radiu

1s is ",(0,t.jsx)(s.code,{children:"50000"}),". Uses the format bias_lonlat=[longitude],[latitude],[radius in meters]. Only one geospatial bias may be provided."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"bias_ip"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:'"true"'})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Bias by Geolocation of IP"})," Biases search based on approximate geolocation of IP address. Set ",(0,t.jsx)(s.code,{children:"bias_ip=true"})," to enable."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"box"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by Bounding Box"}),' Restrict search to a geospatial box determined by the "top-left" and "bottom-right" geolocations. Supply 4 comma separated values ordered ',(0,t.jsx)(s.code,{children:"top_left_lon,top_left_lat,bottom_right_lon,bottom_right_lat"}),". The top-left longitude must be less than the bottom-right longitude, and the top-left latitude greater than the bottom-right latitude. A box which fails either check is ignored. Only one geospatial box can be provided."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"postal_code"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by postal code"})," Restrict results to addresses with a matching full postal code. Case, spaces and hyphens are ignored. For US addresses the full postal code is the nine digit ZIP+4 (",(0,t.jsx)(s.code,{children:"941021234"}),"); filter on ",(0,t.jsx)(s.code,{children:"postal_code_3"})," for a five digit ZIP. For UK addresses use ",(0,t.jsx)(s.code,{children:"postcode"}),"."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"postal_code_2"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by postal code prefix"})," Restrict results to addresses whose postal code starts with the given segment. For US addresses this is the three digit ZIP prefix (sectional center), e.g. ",(0,t.jsx)(s.code,{children:"941"})," for San Francisco."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"postal_code_3"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by short postal code"})," Restrict results to addresses with a matching short postal code. For US addresses this is the five digit ZIP code."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"city"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by city"})," Restrict results to addresses in the named city, town or locality. Case, spaces and accents are ignored, so ",(0,t.jsx)(s.code,{children:"San Francisco"})," and ",(0,t.jsx)(s.code,{children:"sanfrancisco"})," match the same addresses. For UK addresses use ",(0,t.jsx)(s.code,{children:"post_town"}),"."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"state"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by state"})," Restrict results to addresses in the named state, province or region, e.g. ",(0,t.jsx)(s.code,{children:"California"}),". Case and spaces are ignored."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"state_code"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by state code"})," Restrict results to addresses with a matching state or region code, e.g. the two letter USPS state abbreviation ",(0,t.jsx)(s.code,{children:"CA"}),". Case is ignored."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"bias_postal_code"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Bias by postal code"})," Boost addresses with a matching full postal code (nine digit ZIP+4 for US addresses). Unmatched addresses still appear, ranked lower."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"bias_postal_code_2"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Bias by postal code prefix"})," Boost addresses whose postal code starts with the given segment (three digit ZIP prefix for US addresses)."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"bias_postal_code_3"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Bias by short postal code"})," Boost addresses with a matching short postal code (five digit ZIP for US addresses)."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"bias_city"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Bias by city"})," Boost addresses in the named city, town or locality. Case, spaces and accents are ignored. For UK addresses use ",(0,t.jsx)(s.code,{children:"bias_posttown"}),"."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"bias_state"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Bias by state"})," Boost addresses in the named state, province or region."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"bias_state_code"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"string"})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Bias by state code"})," Boost addresses with a matching state or region code, e.g. ",(0,t.jsx)(s.code,{children:"CA"}),"."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"is_pobox"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:'"true" | "false"'})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by PO Box"})," ",(0,t.jsx)(s.code,{children:"true"})," restricts results to PO Box addresses; ",(0,t.jsx)(s.code,{children:"false"})," excludes them. For US addresses this is derived from the USPS record type (",(0,t.jsx)(s.code,{children:"P"}),")."]})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"is_business"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:'"true" | "false"'})}),(0,t.jsx)(s.td,{children:"no"}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Filter by business address"})," ",(0,t.jsx)(s.code,{children:"true"})," restricts results to business addresses; ",(0,t.jsx)(s.code,{children:"false"})," excludes them. For US addresses this is derived from the USPS record type (",(0,t.jsx)(s.code,{children:"F"}),", a firm record)."]})]})]})]}),"\n",(0,t.jsx)(s.h2,{id:"response-type",children:"Response Type"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-ts",children:'import type { FindAddressResponse } from "@addresszen/sdk";\n'})}),"\n",(0,t.jsx)(s.h2,{id:"errors",children:"Errors"}),"\n",(0,t.jsxs)(s.p,{children:["HTTP errors throw an ",(0,t.jsx)(s.code,{children:"ApiError"})," with the HTTP ",(0,t.jsx)(s.code,{children:"status"})," and the API error ",(0,t.jsx)(s.code,{children:"code"})," and ",(0,t.jsx)(s.code,{children:"message"}),". Network failures and aborts reject with the runtime's native error. Pass ",(0,t.jsx)(s.code,{children:"throwOnError: false"})," to get ",(0,t.jsx)(s.code,{children:"{ data, error }"})," instead. See ",(0,t.jsx)(s.a,{href:"/docs/sdks/typescript/errors",children:"error handling"}),"."]}),"\n",(0,t.jsx)(s.h2,{id:"example",children:"Example"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-ts",metastring:'title="find-address.ts"',children:'import { createZenClient, findAddress } from "@addresszen/sdk";\n\nexport const example = async () => {\n  const client = createZenClient({ apiKey: "ak_test" });\n  const { data } = await findAddress({\n    client,\n    query: { query: "123 Main St" },\n  });\n  return data;\n};\n'})})]})}function h(e={}){const{wrapper:s}={...(0,i.R)(),...e.components};return s?(0,t.jsx)(s,{...e,children:(0,t.jsx)(a,{...e})}):a(e)}},4056(e,s,d){d.d(s,{R:()=>n,x:()=>c});var r=d(2155);const t={},i=r.createContext(t);function n(e){const s=r.useContext(i);return r.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function c(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:n(e.components),r.createElement(i.Provider,{value:s},e.children)}}}]);