IP Geolocation Lookup AI Agent / LLM
IP and Network IntelligenceEverything an AI coding assistant needs to write a working IP Geolocation Lookup 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 Lookup API — Way2API®
- **Endpoint:** `POST https://app.way2api.com/api/v1/ip/geolocation`
- **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
## What it does
IP Geolocation API — locate an IPv4 or IPv6 address and describe the network behind it. Returns continent, country, state, district, city, postal code and coordinates, plus country metadata (calling code, TLD, languages, flag emoji), the local currency, the full time zone with current offset and DST state, and the network's ASN and owning company. Pass lang to localise place names. ip_address is optional — omit it to look up the IP that called this API. For threat flags, reverse hostname and abuse contacts in the same call, use IP Geolocation Enrichment.
## Request body (application/json)
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `ip_address` | string | no | IPv4 or IPv6 address to locate, 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 \
-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"
},
"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:45.664-0700",
"abbreviation": "PDT",
"is_dst": true
}
}
}
}
```
## Error response — 400
```json
{
"status": "FAILED",
"status_code": 400,
"charged": false,
"success": false,
"message": "'255.255.255.255' 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 Lookup 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 Lookup 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.