https://docs.addresszen.com/assets/js/77266aba.dff84a06.js

1"use strict";(globalThis.webpackChunk_atlas_docs_zen=globalThis.webpackChunk_atlas_docs_zen||[]).push([[6861],{4056(e,n,i){i.d(n,{R:()=>a,x:()=>d});var r=i(2155);const s={},t=r.createContext(s);function a(e){const n=r.useContext(t);return r.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:a(e.components),r.createElement(t.Provider,{value:n},e.children)}},5701(e,n,i){i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>d,default:()=>h,frontMatter:()=>a,metadata:()=>r,toc:()=>o});const r=JSON.parse('{"id":"api-reference","title":"API Reference","description":"A REST service over HTTPS, returning JSON and authenticated with an API key.","source":"@site/docs/api-reference.mdx","sourceDirName":".","slug":"/api/api-reference","permalink":"/docs/api/api-reference","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{"id":"api-reference","slug":"/api/api-reference","title":"API Reference","sidebar_label":"Introduction","hide_table_of_contents":true},"sidebar":"openApiSidebar","previous":{"title":"Overview","permalink":"/docs/api"},"next":{"title":"Find Address","permalink":"/docs/api/find-address"}}');var s=i(5723),t=i(4056);const a={id:"api-reference",slug:"/api/api-reference",title:"API Reference",sidebar_label:"Introduction",hide_table_of_contents:!0},d="API Reference",c={},o=[{value:"Getting Started",id:"getting-started",level:2},{value:"Authentication",id:"authentication",level:2},{value:"Versioning",id:"versioning",level:2},{value:"Rate Limiting",id:"rate-limiting",level:2},{value:"Error Handling",id:"error-handling",level:2},{value:"Response Codes",id:"response-codes",level:2},{value:"Metadata",id:"metadata",level:2},{value:"Testing",id:"testing",level:2},{value:"OpenAPI Specification",id:"openapi-specification",level:2},{value:"Support",id:"support",level:2}];function l(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"api-reference",children:"API Reference"})}),"\n",(0,s.jsx)(n.p,{children:"A REST service over HTTPS, returning JSON and authenticated with an API key."}),"\n",(0,s.jsx)(n.h2,{id:"getting-started",children:"Getting Started"}),"\n",(0,s.jsxs)(n.p,{children:["All API methods are a ",(0,s.jsx)(n.code,{children:"GET"}),", ",(0,s.jsx)(n.code,{children:"POST"}),", ",(0,s.jsx)(n.code,{children:"PUT"}),", ",(0,s.jsx)(n.code,{children:"DELETE"})," or ",(0,s.jsx)(n.code,{children:"OPTIONS"})," request. The\nAPI communicates over both HTTPS and plain HTTP using IPv4 and IPv6. We\nrecommend HTTPS only, although HTTP is available. Appropriate HTTP status codes\nindicate the request status wherever possible."]}),"\n",(0,s.jsx)(n.h2,{id:"authentication",children:"Authentication"}),"\n",(0,s.jsxs)(n.p,{children:["Most requests require an ",(0,s.jsx)(n.strong,{children:"API key"}),". Authenticate by passing ",(0,s.jsx)(n.code,{children:"api_key"})," in the\nquery string:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"api.addresszen.com/v1/autocomplete/addresses?api_key=ak_test&q=parkside\n"})}),"\n",(0,s.jsxs)(n.p,{children:["Alternatively, pass it via the ",(0,s.jsx)(n.code,{children:"Authorization"})," header:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'Authorization: api_key="ak_test" [other_key="foo"]\n'})}),"\n",(0,s.jsx)(n.h2,{id:"versioning",children:"Versioning"}),"\n",(0,s.jsxs)(n.p,{children:["The API is versioned with a URL prefix. The current version is ",(0,s.jsx)(n.code,{children:"/v1/"}),". Breaking\nchanges are released under a new version. The following changes are\nbackwards-compatible and do not trigger a version bump:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Adding new properties to existing responses"}),"\n",(0,s.jsx)(n.li,{children:"Adding new endpoints"}),"\n",(0,s.jsx)(n.li,{children:"Adding new optional request parameters"}),"\n",(0,s.jsx)(n.li,{children:"Changing the order of properties in existing responses"}),"\n",(0,s.jsx)(n.li,{children:"Changing the autocomplete address suggestion format"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"rate-limiting",children:"Rate Limiting"}),"\n",(0,s.jsxs)(n.p,{children:["Each IP address is rate limited at 30 requests per second. Tripping the limit\nreturns a ",(0,s.jsx)(n.code,{children:"503"}),". The autocomplete API carries an additional rate limit. If you\nexpect to breach the limit, ",(0,s.jsx)(n.a,{href:"https://addresszen.com/support",children:"contact us"})," and we\ncan move you to a higher-limit endpoint."]}),"\n",(0,s.jsx)(n.h2,{id:"error-handling",children:"Error Handling"}),"\n",(0,s.jsxs)(n.p,{children:["A successful lookup returns HTTP ",(0,s.jsx)(n.code,{children:"200"})," and a response ",(0,s.jsx)(n.code,{children:"code"})," of ",(0,s.jsx)(n.code,{children:"2000"})," in the\nbody. An error has occurred if the HTTP status code is not ",(0,s.jsx)(n.code,{children:"200"}),", ranging from a\nbenign ",(0,s.jsx)(n.code,{children:"404"})," (resource not found) to more urgent errors (insufficient balance,\nfailed authentication, etc). Every error body also carries a numeric ",(0,s.jsx)(n.code,{children:"code"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"response-codes",children:"Response Codes"}),"\n",(0,s.jsx)(n.p,{children:"The API returns two status indicators:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["The ",(0,s.jsx)(n.strong,{children:"HTTP Status"})," in the status line, adhering to HTTP/1.1 wherever\npossible. ",(0,s.jsx)(n.code,{children:"2XX"})," indicates success; ",(0,s.jsx)(n.code,{children:"4XX"})," and ",(0,s.jsx)(n.code,{children:"5XX"})," indicate client and server\nerrors respectively."]}),"\n",(0,s.jsxs)(n.li,{children:["The ",(0,s.jsx)(n.strong,{children:"API response code"})," in the ",(0,s.jsx)(n.code,{children:"code"})," property of the body, giving a more\nspecific reason when a failure occurs."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"metadata",children:"Metadata"}),"\n",(0,s.jsxs)(n.p,{children:["Requests that affect your balance can be annotated with arbitrary metadata,\nstored with your lookup history and queryable later via the API or dashboard.\nSee ",(0,s.jsx)(n.a,{href:"/docs/guides/tag-and-track",children:"tagging"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"testing",children:"Testing"}),"\n",(0,s.jsxs)(n.p,{children:["Each new account comes with a free test balance. Contact us if you need more for\ntesting and integration. The code samples in this reference use the ",(0,s.jsx)(n.code,{children:"ak_test"}),"\nkey; you can use it too, but it is capped at 5 requests per day. See the\n",(0,s.jsx)(n.a,{href:"/docs/guides/testing",children:"testing guide"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"openapi-specification",children:"OpenAPI Specification"}),"\n",(0,s.jsx)(n.p,{children:"The machine-readable specification is available at:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"https://openapi.addresszen.com",children:"API Reference"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"https://openapi.addresszen.com/openapi.json",children:"OpenAPI v3 JSON"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"https://openapi.addresszen.com/openapi.yaml",children:"OpenAPI v3 YAML"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"https://www.npmjs.com/package/@addresszen/openapi",children:"npm package"})}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"support",children:"Support"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Support: ",(0,s.jsx)(n.a,{href:"mailto:[email protected]",children:"[email protected]"})]}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"https://terms.addresszen.com",children:"Terms of Service"})}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(l,{...e})}):l(e)}}}]);