← Back to Blog
tutorialgetting-startedsdk

Getting Started With PostalDataPI in 5 Minutes

The PostalDataPI Team··3 min read

From Zero to Postal Code Lookups in 5 Minutes

PostalDataPI is a global postal code API that covers 70+ countries with sub-10ms response times. This guide walks you through setup, your first query, and integration with Python or Node.js.

Step 1: Create Your Account

Head to postaldatapi.com/register and sign in with Google, GitHub, or Microsoft. No passwords to manage, no credit card required.

Your account comes with 1,000 free queries so you can build and test your integration before spending a cent.

Step 2: Get Your API Key

After signing in, go to your Account dashboard. Your API key is displayed right there. Copy it — you will need it for every request.

Step 3: Make Your First Query

Using cURL

curl -s -X POST https://postaldatapi.com/api/lookup \
  -H "Content-Type: application/json" \
  -d '{"zipcode": "90210", "apiKey": "YOUR_KEY"}' | jq '{city, state, ST}'

Response:

{
  "city": "Beverly Hills",
  "state": "California",
  "ST": "CA"
}

Using Python

Install the SDK:

pip install postaldatapi

Then use it:

from postaldatapi import PostalDataPI

client = PostalDataPI(api_key="YOUR_KEY")


# Look up a US ZIP code
result = client.lookup("90210")
print(result.city)               # Beverly Hills
print(result.state)              # California
print(result.state_abbreviation) # CA


# Look up a UK postcode
result = client.lookup("SW1A", country="GB")
print(result.city)  # Westminster Abbey


# Look up a German PLZ
result = client.lookup("10115", country="DE")
print(result.city)  # Berlin

Using Node.js

Install the SDK:

npm install postaldatapi

Then use it:

import { PostalDataPI } from "postaldatapi";

const client = new PostalDataPI({ apiKey: "YOUR_KEY" });


// Look up a Japanese postal code
const result = await client.lookup("100-0001", { country: "JP" });
console.log(result.city); // Chiyoda

Available Endpoints

PostalDataPI offers four endpoints, each designed for a specific use case:

  • /api/lookup — Get city and state for a postal code. Perfect for checkout forms and address validation.
  • /api/metazip — Full metadata including latitude, longitude, county, and timezone. Ideal for geocoding and analytics.
  • /api/validate — Check if a postal code exists in a given country. Fast boolean validation for form fields.
  • /api/city — Find all postal codes for a given city. Useful for area-based searches and shipping zone calculations.
All endpoints accept a country parameter (ISO 3166-1 alpha-2 code) and return JSON responses.

Step 4: Add Balance (When You Are Ready)

Your free 1,000 queries will get you through development and initial testing. When you are ready for production, add balance from your account dashboard. The minimum recharge is $5, which gives you approximately 178,000 queries.

There are no monthly fees, no expiring credits, and no tier upgrades. Just add balance when you need it.

What Is Next?

If you run into any issues, reach out at support@postaldatapi.com. We are here to help.
Getting Started With PostalDataPI in 5 Minutes | PostalDataPI Blog