IP Blacklist Check API in Python: 8.8.8.8 JSON

You need to automatically determine whether an IP address is on known email/IP blocklists and act on it from Python. By the end of this article, you’ll call ipXapi’s blacklist check endpoint for 8.8.8.8, read the JSON, and wire up gating logic (is_listed and listed_count) to protect signups, logins, or outbound email.

What you get from an IP blacklist check

An IP blacklist check tells you if a specific IP address appears on common blocklists used by mail providers, fraud systems, or network filters. Developers typically use it to:

• Block or review risky traffic during signup, login, or payment flows.
• Throttle or quarantine messages from listed IPs in email services.
• Flag events in SIEM/SOC pipelines for additional scrutiny.

The core signals you’ll use are:

• is_listed — a boolean you can gate on immediately.
• listed_count — how many lists include the IP, useful to adjust thresholds.

In this guide we’ll call the documented sample IP 8.8.8.8 and parse the official JSON. Live flags can change, so don’t assume the same values for your traffic.

Endpoint, auth, and request shape

ipXapi provides a dedicated endpoint for blacklist lookups:

• Method: GET
• Path: /api/blacklist-check?ip=

You authenticate with a Bearer key. If you don’t have one yet, start with the 7‑day trial or 50 requests when you Register. For reference and endpoint details, see the Documentation and the MCP.

Call the API for 8.8.8.8

Here’s a copy‑pasteable curl for the documented IP:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://ipxapi.com/api/blacklist-check?ip=8.8.8.8"

curl 'https://ipxapi.com/api/blacklist-check?ip=8.8.8.8' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_KEY' 

Python usage and gating logic

You’ll typically call the endpoint, check success, then gate on is_listed and listed_count. If success is false or required fields are missing, treat the outcome as unknown and fail safe (e.g., allow but log, or hold for manual review) depending on your use case.

import os, urllib.request
req = urllib.request.Request(
    "https://ipxapi.com/api/blacklist-check?ip=8.8.8.8",
    headers={"Authorization": "Bearer " + os.environ["IPXAPI_KEY"], "Accept": "application/json"},
)
print(urllib.request.urlopen(req).read().decode())

If you prefer a minimal Python example that mirrors the same contract:

import os
import requests

API_KEY = os.environ.get("IPXAPI_KEY", "YOUR_API_KEY")
IP = "8.8.8.8"

resp = requests.get(
    "https://ipxapi.com/api/blacklist-check",
    params={"ip": IP},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=10,
)
data = resp.json()

# Defensive checks in case fields are missing
success = data.get("success", True)  # default true if not present
if not success:
    # Inspect error details if provided; decide fail-open or fail-closed
    raise RuntimeError("Blacklist check failed (success=false)")

is_listed = data.get("is_listed")
listed_count = data.get("listed_count")

if is_listed is None or listed_count is None:
    # Don’t break your pipeline; choose a conservative default
    # For example: treat as not listed but log, or queue for review
    print("Missing fields; proceeding with defaults")
else:
    if is_listed:
        # Adjust thresholds with listed_count if you need stricter gating
        print(f"IP is listed on {listed_count} list(s)")
    else:
        print("IP is not listed")

Official JSON for 8.8.8.8 and what to read

The following is the official product sample for the endpoint. Do not assume it reflects your users’ IPs or today’s live status.

{
  "ip": "8.8.8.8",
  "is_listed": false,
  "checked_blacklists": 100,
  "listed_count": 0,
  "ok_count": 100,
  "timeout_count": 0,
  "listed_blacklists": [],
  "timeouts": []
}

What you’ll actually use from the JSON:

• success — if provided and false, treat the response as an error and do not rely on blacklist signals.
• is_listed — primary boolean to determine if an IP appears on one or more lists.
• listed_count — numeric value you can use to tier responses (e.g., stricter action when the count is higher).

If additional fields are present, use them for observability or reporting as needed. When any field you rely on is missing, use a controlled fallback so your flow degrades safely.

Go live quickly

Steps

1. Register — start with the 7‑day trial or 50 requests.
2. Copy your Bearer key from the dashboard.
3. Send GET /api/blacklist-check?ip= with your key in the Authorization header.
4. Gate on is_listed and listed_count in your pipeline.

Error handling and unknown states

Design for the following situations:

• HTTP errors or timeouts: retry with backoff and set a maximum attempt policy appropriate for your user experience.
• success=false in the JSON: log or alert, then choose whether to fail open (allow) or fail closed (block) based on your risk tolerance.
• Missing fields: do not crash the flow; provide sensible defaults or route to review.

Operational guidance

• Caching: Blocklist status can change. Cache short‑term only to reduce latency and control usage, but refresh often enough for your risk posture. In high‑volume flows, consider separate caches for negative and positive results.
• Idempotency: For the same IP during a short window, reuse results to avoid unnecessary calls.
• Observability: Log the ip you queried, success, is_listed, and listed_count to measure impact on conversion and fraud.
• Pagination: Not applicable for a single-IP check; you’ll make one request per IP you need to score.
• Timezones and units: The primary fields you act on are booleans and counts. If the payload includes timestamps or additional details, parse them as provided and standardize to your system’s timezone convention.

Security and compliance notes

• Key management: Store your Bearer token in a secret manager or environment variable. Rotate on a schedule.
• Least privilege: Scope access to the minimal systems that need to call the endpoint.
• Audit trails: Record reasons for blocks when is_listed is true and retain enough context to explain decisions.

Testing strategy

• Use the documented sample IP 8.8.8.8 to validate your request path, auth, and parsing. Remember that live flags can change.
• Exercise both branches: simulate success=false and missing fields in local tests to ensure your fallback logic works.
• Backoff policy: verify that transient errors don’t stall user flows.

Pricing and plan start

The Basic plan is $29.99/mo with a 7‑day trial or 50 requests. You can start immediately when you Register.

FAQ

How do I authenticate?
Use an Authorization header with your Bearer key. Example: Authorization: Bearer YOUR_API_KEY

What endpoint do I call?
GET /api/blacklist-check?ip= with the IP you want to check, for example ip=8.8.8.8.

Which fields should I gate on?
Gate on is_listed and use listed_count to tune your actions (e.g., stricter throttling for higher counts).

How should I handle success=false?
Treat it as an error condition. Log it, alert if appropriate, and choose a fail-open or fail-closed posture consistent with your risk model.

Can I cache results?
Yes, but keep caches short because blocklist membership can change. Consider different TTLs for positive and negative results based on your tolerance for staleness.

Start checking IPs in minutes: grab your key and ship your integration. Register for the trial, review the Documentation, and, if you need more detail on models and platform access, visit the MCP.