formspree.io

A postal code API returns structured location data for a given ZIP Code or Canadian postal code. A typical response includes the code itself, city, state or province, county, latitude/longitude, and — where available — ZIP+4 detail. More complete services add time zone, area codes, boundary geometry, and demographic fields. You send a code (or an address), and the API sends back a machine-readable record you can store, validate, or display.

This article explains what those responses contain, how requests are usually shaped, and where postal code data fits into real applications.

First, clear up the word "code"

The keyword "code" is overloaded, and that causes real confusion for developers:

• Postal code — the ZIP Code (U.S.) or postal code (Canada) that identifies a delivery area.
• API key — the credential you use to authenticate your requests. It is not postal data.
• Source code — the program you write to call the API.

When someone searches for "postal code API code," they usually want example request/response code for a postal code service. The rest of this article treats it that way.

What a postal code API actually returns

Response fields vary by provider and endpoint, but the core set is fairly consistent. A single-code lookup commonly returns:

Richer datasets add 90+ fields: boundaries, population, income, elevation, and more. You rarely need all of them — request only what your application uses.

A representative JSON response

{
  "postal_code": "90210",
  "city": "Beverly Hills",
  "state": "CA",
  "county": "Los Angeles",
  "latitude": 34.0901,
  "longitude": -118.4065,
  "timezone": "America/Los_Angeles",
  "area_codes": ["310", "424"]
}

XML responses carry the same information in tag form. Choose based on what your stack parses most easily; JSON is the common default.

Common request patterns

Most postal code APIs support four patterns. Knowing which one you need prevents wasted calls.

1. Lookup by code

You have a code and want its details. This is the simplest and fastest call.

GET /lookup?code=90210

2. Reverse lookup by address

You have a street address and want to confirm or complete the code. This is the pattern behind checkout address validation.

GET /validate?street=...&city=...&state=...

3. Radius search

You have a center point and want all codes within a distance. Useful for store locators and delivery zones.

GET /radius?code=90210&miles=10

4. Batch validation

You have a file of addresses and want them cleaned in bulk. Batch endpoints trade latency for throughput and usually have their own limits.

Handling missing and ambiguous matches

Real data is messy. Plan for these cases:

• No match — the code doesn't exist or the address is malformed. Return a clear error rather than a silent empty object.
• Multiple matches — a city name may map to several codes, or a code may span several acceptable city names. Decide whether to pick the primary or return a list.
• Partial match — the street is valid but the ZIP+4 isn't. Fall back to the 5-digit code.
• Stale data — codes are added, retired, and reassigned. Refresh your dataset on a regular schedule.

A practical rule: validate at the point of entry, store the normalized result, and never re-derive it later from raw user input.

Practical use cases

• Checkout address validation — catch typos before shipping, reduce failed deliveries.
• Shipping zone lookup — map a code to a zone, carrier route, or rate table.
• Data enrichment — append county, coordinates, or demographics to existing records.
• Store and service locators — radius search to find nearby branches or coverage areas.
• Territory and tax logic — county and boundary data drive jurisdiction rules.

Licensing and data-source considerations

Postal code data originates with national authorities — USPS in the United States and Canada Post in Canada. Providers license and repackage it, which is why accuracy, update frequency, and field coverage differ between services. Before committing:

• Confirm the data source and how often it refreshes.
• Check whether ZIP+4 and boundary data are included or sold separately.
• Review usage limits and whether batch processing is allowed.
• Read the license terms for redistribution and storage.

Pricing and plan details change, so check the provider's current documentation rather than relying on secondhand figures.

Getting started

1. Decide which request pattern you need (lookup, reverse, radius, or batch).
2. Pick the fields you'll actually store.
3. Write a small test call and inspect the raw response.
4. Add error handling for no-match and ambiguous cases.
5. Cache results where the same codes repeat.

A postal code API is ultimately a translation layer: you give it a code or an address, and it gives back structured location facts. Understand the fields, match them to your use case, and handle the messy edges — that's most of the work.

To connect a static HTML form to Formspree, point the form's action at your Formspree endpoint (https://formspree.io/f/{form_id}), set method="post", and give each input a name attribute. Formspree receives the submission, validates it, filters spam, emails you, and stores it in your Formspree inbox — no server code on your side. This works for any static host (GitHub Pages, Netlify, plain HTML files) and requires only a Formspree account and a form ID.

What you need before starting

• A Formspree account and a form created in it, which gives you a form ID (the {form_id} segment in the endpoint).
• An HTML page you can edit, hosted anywhere or opened locally.
• No backend, database, or mail server — Formspree's API handles submission processing.

Step 1: Write the form markup

Use a standard HTML <form> with the Formspree endpoint as the action. Every field you want to receive must have a name:

<form action="https://formspree.io/f/{form_id}" method="post">
  <label for="email">Your Email</label>
  <input name="Email" id="email" type="email">
  <button type="submit">Submit</button>
</form>

The name value becomes the field label in your submissions, so use readable names (Email, Message, Company) rather than internal codes.

Step 2: Replace {form_id} with your real ID

Swap the placeholder for the ID from your Formspree dashboard. The resulting URL looks like https://formspree.io/f/abcdwxyz. If you skip this step, submissions go nowhere.

Step 3: Submit a test entry

Open the page, fill in the form, and submit. Expected results:

1. The browser posts to Formspree and you see a confirmation (or are redirected, depending on your form settings).
2. The submission appears in your Formspree Inbox.
3. An email notification arrives at the address tied to your account.

Formspree's own documentation states you can "create a working form in seconds" and see submissions "in under a minute," so a missing entry usually points to a markup error rather than delay.

What happens after submission

According to Formspree, the pipeline is:

You can also add reCAPTCHA with one click or define custom spam rules if the default filter isn't enough.

Common snags and how to check them

• Nothing arrives in the inbox. Confirm the action URL contains your actual form ID and that method="post" is present.
• Fields are missing from submissions. Any input without a name attribute is not sent. Add names to every field, including textareas and selects.
• Spam getting through. Enable reCAPTCHA or add custom rules in the form settings; Formspree's default filter is machine-learning based but tunable.
• Wrong destination email. Notifications go to the address configured for that form, so check the form's settings rather than the page markup.

When this approach fits — and when it doesn't

The plain-HTML method is the right choice when you have a static site and want submissions handled without writing or hosting server code. If you need dynamic behavior — conditional fields, multi-step forms, or programmatic submission — Formspree also offers a JavaScript library and CLI with a React library and CI/CD deployment for production forms. For a simple contact or signup form, the HTML-only route is the shortest path.

Pricing tiers and account limits are listed on Formspree's Plans page; check that page for current terms before relying on a specific submission volume.

OpenAPI-generated API documentation is reference documentation that is produced automatically from an OpenAPI description file rather than written by hand. You write (or generate) a machine-readable specification of your API — endpoints, parameters, request bodies, responses, schemas, and auth — and a documentation tool reads that file and renders a browsable, often interactive reference site. The spec becomes the single source of truth; the docs become a build artifact.

This differs from manually written docs in one fundamental way: with hand-written docs, the prose is the source of truth and the API is described separately. With spec-driven docs, the API description is the source, and every page, table, and code sample is derived from it.

How the workflow actually runs

A typical spec-driven documentation pipeline has five stages:

1. Author or generate the spec. You either write an OpenAPI document by hand (YAML or JSON), or generate it from code annotations, framework metadata, or a design-first editor. Design-first means the spec is written before implementation; code-first means it is extracted from existing code.
2. Validate and lint. The spec is checked against the OpenAPI schema and against style rules — consistent naming, required descriptions, no undocumented 4xx responses, no orphaned schemas.
3. Bundle and transform. Multi-file specs are combined, $ref pointers are resolved, and the document is optionally split into per-tag or per-version outputs.
4. Render. A documentation tool converts the spec into HTML: an endpoint list, a sidebar of operations, parameter tables, response schemas, and a "try it" console.
5. Publish and version. The rendered site is deployed, and each API version gets its own snapshot so consumers can read docs matching the version they call.

Steps 2 through 5 are usually automated in CI. If the spec fails validation, the docs build fails — which is the point.

Spec-driven vs. hand-written documentation

The practical conclusion most teams reach: generate the reference, write the guides. Reference material is repetitive and mechanical, which is exactly what generation is good at. Conceptual explanations, migration notes, and tutorials carry judgment that a spec cannot express.

What you get out of the box

Generated reference pages commonly include:

• An operation list grouped by tag or path, with HTTP method and path.
• Parameter tables showing name, location (path, query, header, cookie), type, required flag, and description.
• Request and response schemas rendered as expandable trees, including nested objects and arrays.
• Authentication details pulled from the securitySchemes section.
• Interactive request consoles that let a reader send a real call from the browser.
• Generated code samples in several languages, derived from the same schemas.
• Multiple output formats, such as a static site, a single HTML file, or a mock server.

Because all of these come from one document, changing a field name in the spec updates the parameter table, the schema tree, and every code sample at once.

Where spec-driven documentation breaks down

Generation is not free. The trade-offs are real:

Spec quality becomes documentation quality. A field with no description produces a table row with an empty cell. A vague summary produces a vague heading. Tools can enforce presence of descriptions via linting, but they cannot enforce that the description is useful.

Customization has limits. If you need a page that does not map to an OpenAPI concept — a conceptual overview, a pricing explanation, a comparison of two endpoints — you write it outside the generator and link to it.

Not everything is expressible. Webhooks, streaming responses, long-polling behavior, and complex multi-step flows are awkward or impossible to describe fully in OpenAPI. Those need prose.

The spec can go stale. If the spec is maintained separately from the implementation, it drifts just like hand-written docs. The mitigation is to generate the spec from code, or to test the implementation against the spec in CI.

Interactive consoles need care. A "try it" button that hits a production API with real credentials is a security and rate-limit problem. Point it at a sandbox, or disable it.

Deciding whether to adopt it

Adopt spec-driven reference documentation if most of these are true:

• Your API has more than a handful of endpoints, or changes frequently.
• You ship client SDKs or code samples in more than one language.
• Multiple teams consume the API and need a consistent, always-current reference.
• You already have, or are willing to maintain, an OpenAPI description.

Stay with hand-written docs, or a hybrid, if:

• Your API is small and stable, and the reference fits on one page.
• Your documentation is mostly conceptual and contains little endpoint-level detail.
• You cannot commit to keeping the spec in sync with the implementation.

A reasonable middle path: generate the reference from the spec, and hand-write the getting-started guide, authentication walkthrough, and error-handling page. Link the two directions so readers can move from concept to endpoint and back.

A minimal starting checklist

1. Produce one valid OpenAPI document for a single API version.
2. Add a linter with rules for descriptions, operation IDs, and error responses.
3. Wire the docs build into CI so a failing spec fails the build.
4. Render the reference and review it as a reader, not as the author.
5. Write the two or three conceptual pages the generator cannot produce.
6. Version the published docs alongside the API version.

The core idea is simple: describe the API once, in a format both machines and humans can read, and let the reference documentation fall out of that description. Everything else — tooling, hosting, interactivity — is a detail on top of that decision.

Choose HTML forms if you want the simplest possible setup: point a standard <form> at your Formspree endpoint and you're done, no server code required. Choose JavaScript forms if you're building with React and want the Formspree CLI, a React library, and CI/CD deployment for production. Choose Formbutton if you want a popup form you can drop onto any site with a copy/paste snippet. All three submit to the same Formspree backend, so the differences are about your frontend stack and how much control you need.

The three options side by side

HTML forms: the lowest-friction path

Formspree's HTML approach requires no server code. You write a normal form and set its action to your Formspree endpoint, using method="post":

<form action="https://formspree.io/f/{form_id}" method="post">
  <label for="email">Your Email</label>
  <input name="Email" id="email" type="email">
  <button type="submit">Submit</button>
</form>

Replace {form_id} with the ID from your Formspree account. The expected result is that submissions arrive in your Formspree Inbox and trigger your configured notifications.

Use this when: you have a static site or a page where you can edit HTML directly, and you don't want a build pipeline. Watch for: the endpoint and field names must match your form configuration; a typo in the action URL means submissions go nowhere.

JavaScript forms: for React and CI/CD workflows

The JavaScript path is aimed at developers building dynamic forms. Formspree provides a CLI and a React library, and the site explicitly supports deploying production forms with CI/CD. This is the option to pick when your form lives inside a React application, needs to be generated or versioned as part of a build, or must ship through your existing deployment pipeline.

Use this when: your frontend is React-based or you want form configuration managed in code and deployed automatically. Watch for: this adds tooling and a build step, so it's overkill for a single static contact form.

Formbutton: popup forms with a snippet

Formbutton is a copy/paste snippet that overlays a popup form on your site. You don't design a form section or wire up an endpoint manually; you paste the snippet and get an attractive popup.

Use this when: you want to capture leads or feedback without restructuring a page, or you're adding a form to a site where inline form markup is inconvenient. Watch for: popups interrupt the browsing experience, so placement and trigger timing matter more than with an inline form.

What happens after submission (same for all three)

Whichever option you choose, the backend behavior is identical. According to Formspree, after a submission:

1. Spam is blocked and data validated — server-side validation plus machine-learning spam filtering.
2. Email notifications and auto-responses are sent — templates are customizable.
3. Submissions are saved to the Formspree Inbox — with daily analytics and export to CSV or JSON.
4. Third-party integrations fire — direct integrations include Google Sheets, Airtable, Slack, HubSpot, Mailchimp, Notion, Stripe, and webhooks, with no Zapier required.

Spam controls include the Formshield machine-learning filter, one-click reCAPTCHA, and custom rules.

How to decide

• Static HTML site, fastest setup → HTML forms.
• React app or CI/CD-managed forms → JavaScript forms.
• Popup capture on an existing page → Formbutton.

If you're unsure, start with HTML forms: it's the least setup and you can migrate to the JavaScript library later if your frontend grows into React. For current plan details and limits, check Formspree's Plans page, since feature availability can vary by plan.

After a visitor submits a form pointed at your Formspree endpoint, Formspree runs a fixed sequence: it validates the data server-side and filters spam, sends email notifications and any auto-responses, saves the submission to your Formspree Inbox with analytics and CSV/JSON export, and triggers any third-party integrations you've connected. You don't run any server code for this — your form's action attribute points at https://formspree.io/f/{form_id} and Formspree handles the rest.

The submission pipeline, step by step

1. Spam blocking and server-side validation

Formspree validates submitted data on its servers rather than in the browser, so checks can't be bypassed by editing client-side code. Spam protection runs at the same stage, using automatic filtering, optional captchas, and custom rules:

• Formshield — machine-learning spam filtering applied automatically.
• reCAPTCHA — added with one click if you want an explicit challenge.
• Custom rules — your own rules to fight specific spam patterns.

2. Email notifications and auto-responses

Formspree sends email notifications for new submissions, and can send auto-responses to the person who submitted the form. The email templates are fully customizable, so the notification your team receives and the confirmation your visitor receives can both be shaped to match your brand.

3. Saving to the Formspree Inbox

Every submission is stored in the Formspree Inbox, where you can view submissions, see daily analytics reports, and export data as CSV or JSON. This matters if email delivery fails or you need a record outside your inbox — the submission isn't lost with a bounced notification.

4. Triggering third-party integrations

If you've connected integrations, they fire after the submission is processed. Formspree lists direct integrations (no Zapier required) with services including:

Webhooks are the escape hatch: if your destination isn't on the list, a webhook lets your own endpoint receive the submission data.

A concrete example

Suppose a freelancer hosts a portfolio site on static hosting with a contact form:

<form action="https://formspree.io/f/{form_id}" method="post">
  <label for="email">Your Email</label>
  <input name="Email" id="email" type="email">
  <button type="submit">Submit</button>
</form>

When a visitor submits it, Formspree checks the data and screens it for spam, emails the freelancer a notification, optionally sends the visitor an auto-response, stores the entry in the Inbox where it appears in analytics and can be exported, and — if a Slack integration is connected — posts a message to the freelancer's channel. No server, database, or mail configuration is involved on the site owner's side.

What this means for your setup decisions

• If you need a submission record you control, plan on the Inbox export (CSV/JSON) or a webhook/integration to your own system — the Inbox is the built-in store, not your database.
• If notification reliability matters, the Inbox copy is your fallback when email doesn't arrive.
• If you're automating setup with an AI agent, Formspree publishes an llms.txt with setup instructions for LLMs.
• If you want popup forms without writing markup, Formspree's Formbutton lets you copy/paste a snippet for an overlay form.

Pricing and plan limits are not covered in the material available here; check Formspree's Plans page before assuming a tier covers your submission volume.