IP Geolocation Enrichment AI Agent / LLM
IP and Network IntelligenceEverything an AI coding assistant needs to write a working IP Geolocation Enrichment integration without opening another page: endpoint, authentication, parameters, a real request, both response shapes and the platform rules it cannot infer from a single example. Copy the brief below and paste it into Claude, Cursor, GitHub Copilot, ChatGPT or any other agent.
Machine-readable spec — Markdown
# IP Geolocation Enrichment API — Way2API®
- **Endpoint:** `POST https://app.way2api.com/api/v1/ip/geolocation/full`
- **Auth:** `Authorization: Bearer YOUR_API_KEY` (or `X-API-Key: YOUR_API_KEY`)
- **Content-Type:** `application/json`
- **Category:** IP and Network Intelligence
- **Availability:** Available worldwide
- **Docs:** https://app.way2api.com/documentation/ip-geolocation-full
## What it does
IP Geolocation Enrichment API — everything IP Geolocation returns, plus the full threat-intelligence block (threat score, Tor / proxy / VPN / relay / bot / spam / known-attacker flags), the reverse hostname, geolocation accuracy_radius and confidence, the US dma_code, and the network's registered abuse contact — in one billable call instead of three. The shared fields are byte-for-byte identical to the base tier, so you can move between the two without changing how you read a response. Built for high-stakes decisions: account takeover checks, payment risk and geo-compliance.
## Request body (application/json)
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `ip_address` | string | no | IPv4 or IPv6 address to look up, e.g. 8.8.8.8. Optional — if omitted, the IP that called this API is used. |
| `lang` | string | no | Language for location names: en (default), de, ru, ja, fr, cn, es, cs, it, ko, fa, pt. |
## Example request
```bash
curl -X POST https://app.way2api.com/api/v1/ip/geolocation/full \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ip_address":"8.8.8.8"}'
```
## Success response — 200
```json
{
"status": "SUCCESS",
"status_code": 200,
"charged": true,
"success": true,
"message": "",
"message_code": "OK",
"order_id": "W2A1739512345abcdef01",
"data": {
"order_id": "W2A1739512345abcdef01",
"result": {
"ip_address": "8.8.8.8",
"location": {
"continent_code": "NA",
"continent_name": "North America",
"country_code": "US",
"country_code3": "USA",
"country_name": "United States",
"country_name_official": "United States of America",
"country_capital": "Washington, D.C.",
"state": "California",
"state_code": "US-CA",
"district": "Santa Clara",
"city": "Mountain View",
"postal_code": "94043-1351",
"latitude": 37.4224,
"longitude": -122.08421,
"is_eu": false,
"geoname_id": "6301403",
"locality": "Mountain View",
"accuracy_radius": 38.288,
"confidence": "low",
"dma_code": "807"
},
"country_metadata": {
"calling_code": "+1",
"tld": ".us",
"languages": [
"en-US",
"es-US",
"haw",
"fr"
],
"flag_emoji": "🇺🇸"
},
"network": {
"route": "8.8.8.0/24",
"connection_type": "",
"is_anycast": true
},
"currency": {
"code": "USD",
"name": "US Dollar",
"symbol": "$"
},
"asn": {
"number": "AS15169",
"organization": "Google LLC",
"country": "US",
"type": "business",
"domain": "google.com",
"registry": "ARIN",
"allocated_on": "2000-03-30"
},
"company": {
"name": "Google LLC",
"type": "hosting",
"domain": "google.com"
},
"time_zone": {
"name": "America/Los_Angeles",
"offset": -8,
"offset_with_dst": -7,
"current_time": "2026-08-04 06:33:59.826-0700",
"abbreviation": "PDT",
"is_dst": true
},
"hostname": "dns.google",
"abuse_contact": {
"name": "Abuse",
"organization": "Abuse",
"address": "1600 Amphitheatre Parkway, Mountain View, CA, 94043, United States",
"emails": [
"[email protected]"
],
"phones": [
"+16502530000"
],
"network": "8.8.8.0/24",
"country": "US"
},
"security": {
"threat_score": 5,
"is_anonymous": false,
"is_tor": false,
"is_proxy": false,
"is_residential_proxy": false,
"proxy_providers": [],
"proxy_confidence": 0,
"proxy_last_seen": "",
"is_vpn": false,
"vpn_providers": [],
"vpn_confidence": 0,
"vpn_last_seen": "",
"is_relay": false,
"relay_provider": "",
"is_known_attacker": false,
"is_bot": false,
"is_spam": false,
"is_cloud_provider": true,
"cloud_provider": "Google LLC"
}
}
}
}
```
## Error response — 400
```json
{
"status": "FAILED",
"status_code": 400,
"charged": false,
"success": false,
"message": "'127.0.0.1' is a reserved (bogon) IP address.",
"message_code": "REQUEST_FAILED",
"order_id": "W2A1739512345abcdef01",
"data": {
"order_id": "W2A1739512345abcdef01",
"error_code": "Locked"
}
}
```
## Integration rules
- Every response is JSON carrying `status`, `status_code`, `charged`, `success`, `message`, `message_code` and (once a call reaches the provider) `order_id`. The verification payload is under `data.result`.
- `charged` (boolean) is the authority on billing. Do NOT infer it from the HTTP status: `422` is returned both for input we rejected (not charged) and for a lookup the provider ran and billed us for that returned a negative result (charged).
- `message_code` is a fixed vocabulary — branch on it instead of parsing `message`. Values: `OK`, `ACCEPTED`, `PROVIDER_NO_RESPONSE`, `VERIFICATION_FAILED`, `NO_RECORD_FOUND`, `INVALID_INPUT`, `REQUEST_FAILED`, `MISSING_API_KEY`, `INVALID_API_KEY`, `INSUFFICIENT_BALANCE`, `NO_API_ACCESS`, `NOT_FOUND`, `RATE_LIMITED`, `INTERNAL_ERROR`, `PROVIDER_UNAVAILABLE`.
- `success` reports the verification outcome; `status` reports the ORDER lifecycle (`SUCCESS`/`PENDING`/`FAILED`). They differ on a charged negative result: the order completed and was billed while the verification did not pass.
- A failed verification is still a successful HTTP call — the outcome lives in the response body, so do not treat `200` as "verified".
- Status codes: `200` result returned, `202` pending or provider did not respond (both charged — quote the `order_id`), `401` missing/invalid key, `402` insufficient balance, `403` no access to this service, `422` see `charged`, `429` rate limited (honour the `Retry-After` header), `503` temporarily unavailable.
- Rate limits are per API key, per service, on a 1-minute sliding window.
- Load the API key from an environment variable or secret store. Never hard-code it, never commit it, and never ship it in client-side code — calls must be made from your backend.
Prompts to pair it with
- Write a production-ready IP Geolocation Enrichment integration in PHP using this spec, with error handling and retries.
- Given this spec, generate typed request/response models and a client class.
- Review my existing IP Geolocation Enrichment integration against this spec and list what I handle incorrectly.
⚠ Before you paste generated code
Never let an assistant hard-code your API key — load it from an environment variable or a
secret store, and call this endpoint from your backend only. A failed verification is still a
successful HTTP call, so check the success field in the body
rather than treating 200 as verified.