Summary Russell Bateman February 2026 last update:

I researched Melissa Data to refresh my memory. There are 3 API sets in Melissa Data:

Relevant to geocoding:
• Personator Consumer appends precise rooftop-level geocodes (latitude/longitude) along with demographic information to verify, update and enrich consumer contact data.
• Global Address Verification standardizes, verifies and appends geocodes for addresses across 240+ countries and territories.

Generic geocoding:
• Melissa Data offers a dedicated GeoCoder API and Street Route for distance calculations.

Irrelevant to geocoding:
• SmartMover focuses primarily on move updates using NCOALink (USPS data) to provide current addresses, not geocoding.

Then, I asked Cursor AI about:

What do you know about Melissa Data's Global Address Verification and Personator Consumer APIs? I want to discuss
creating a Sprint Boot based HTTP(S) service as a private (but licensed-use) interface to Melissa Data.

It gave me:

Global Address Verification

• Purpose: Verify, correct, and standardize mailing addresses worldwide.
• Coverage: 240+ countries/territories.
• Endpoint: /V3/WEB/GlobalAddress/doGlobalAddress (hosts like globaladdress.melissadata.net).
• Capabilities: Single/multi-line input, standardized output, WGS-84 geocoding, parsed components or mailing-label format, UTF-8/accent support.
• Authentication: License key passed as id (or equivalent) in the request.

Personator Consumer

• Purpose: CASS/DPV address verification plus consumer/contact verification and enrichment.
• Endpoint: https://personator.melissadata.net/v3/WEB/ContactVerify/doContactVerify
• Actions: Check (validate/correct), Verify (link to address/email/phone), Move (updated address), Append (demographics, census, etc.).
• Inputs: Address, email, phone, name; centric point can be address, email, or phone.
• Authentication: Same license key (id) in the request.

Licensing & rate limiting

• Licensing: Subscription (yearly, tiers) or Credits (pay-as-you-go). Same license string for both; no separate "Consumer API" license name—you get access per product (Global Address, Personator, etc.).
• Rate limits (approximate): Credit ~5/sec, Self-Service ~12/sec, Business ~50/sec, Enterprise ~100/sec. Also annual caps. 429 when exceeded; 401 for invalid/expired license or exceeded limit.
• Best practice: Single-threaded + batching (e.g. 100 records per POST where supported) to avoid 429s.

Spring Boot proxy as a private, licensed-use interface

A Spring Boot HTTP(S) service in front of Melissa fits "private but licensed-use" well: your apps call your API; only the proxy talks to Melissa and holds the license key.

Benefits

1. License isolation: License key lives only in the proxy (e.g. config/vault); clients never see it.
2. Single place for compliance: Enforce acceptable use, logging, and audit in one service.
3. Unified API: You can normalize Global Address vs Personator behind one REST surface (e.g. /verify/address, /verify/contact, /append).
4. Rate limiting and resilience: Implement your own throttling, queuing, retries (including 429 backoff), and circuit breakers so many internal callers don't blow Melissa's limits.
5. Caching: Optional caching of verification results (within license/permissible-use constraints) to reduce calls and cost.
6. HTTPS + authentication: Expose only HTTPS and enforce your own authentication (API key, JWT, mTLS, etc.) so only authorized internal systems use the proxy.

Design choices to decide

• Pass-through vs. abstraction:
  • Pass-through: Proxy forwards requests to Global Address/Personator with minimal changes (add id, maybe rewrite host/path). Easiest; you stay aligned with Melissa's current API.
  • Abstraction: Your own data-transfer objects (DTO) and endpoints; proxy maps to Melissa's parameters and responses. More work but stable for clients if Melissa changes URLs or parameters.
• One service vs. two: Single Spring Boot app with two "backends" (Global Address + Personator) is usually simpler; separate services only if you need different scaling or release cycles.
• Rate limiting: Use a single outbound queue or semaphore keyed by license so you don't exceed Melissa's per-license limits (and handle 429 with backoff/retry).
• Idempotency / idempotency keys: If clients retry, optional idempotency keys at your API can avoid double-counting usage or duplicate side effects.
• Logging and audit: Log requests/responses (or hashes) and results for compliance and debugging, while avoiding logging full PII if your policy forbids it.

Technology fit

• Spring Boot 3 + WebFlux or MVC: Both work; WebFlux is natural if you want non-blocking outbound calls to Melissa and backpressure.
• Outbound: WebClient (or RestTemplate) to Melissa's HTTPS endpoints; centralize base URLs and timeouts.
• Configuration: License key and Melissa base URLs from application.yml or a secret manager (e.g. Vault, K8s secret); never in client-facing APIs or logs.
• Resilience: Consider Resilience4j (or Spring Retry) for retries with backoff on 429/5xx and optional circuit breaker if Melissa is down.

If you share how you want clients to call the proxy (e.g. "same JSON as Personator" vs "our own small DTO"), I can outline concrete endpoints, a minimal Spring Boot structure, and where to add license injection, rate limiting, and 429 handling.

Then, I asked Cursor:

Hypothetically, if I already have some kind of service written in Python—that I want to discard—can you nevertheless
read it and re-create its entry points and semantics in a new service (in Java using Spring Boot as already discussed)
so that I don't lose backward compatibility?

Cursor answered:

You’ll bring the Python service in once the project starts.

When you have it, you can use this as a short playbook so nothing gets lost and the Java service stays backward compatible.

When you provide the Python service

1. Share the code Include everything that defines the HTTP API: main app, route registration and any wrappers that call Melissa (e.g. Flask/FastAPI routes, requests calls to Global Address / Personator).
2. What to capture (so we can re-create it in Spring Boot)
   • Entry points: Base URL prefix (if any), path patterns, HTTP methods (GET/POST etc.).
   • Request contract: Query params, headers, body shape (JSON/XML/form), required vs optional.
   • Response contract: Status codes, body format (JSON/XML), error payload shape.
   • Melissa usage: Which endpoints call Global Address vs Personator, which actions (Check, Verify, Append, Move), and how Python request fields map to Melissa’s id, act, opt, a1, postal, etc.
   • Behavior: Redirects, default values, validation rules, and how Python turns Melissa errors (e.g. 429/401) into responses to the client.
3. What we’ll do in Spring Boot
   • Implement the same paths and methods.
   • Match request/response semantics (same query/body and status/body where feasible).
   • Keep the license key server-side only and call Melissa from the new service.
   • Optionally add a short "API compatibility" section in the README or docs that maps old Python routes to the new ones (e.g. POST /verify/address → "same path, same contract").

You don’t need to do the extraction yourself unless you want to; once the Python code is in the workspace or pasted, I (or a future session) can read it, list the entry points and semantics, and then outline or implement the Spring Boot service to match.