API Carian Geo-IP

#What GeoIP solves

GeoIP helps you understand who’s connecting — network owner (ASN), country/region, and city-level signals — so you can do geo-based routing, regional compliance, personalization, and abuse controls without friction.

#Endpoints & when to use them

#POST /v1/geoip/asn — ASN Lookup

• Best for: Network-level decisions (hosting vs ISP vs corporate), bot/automation heuristics, traffic shaping.
• Output: asn (number), org (owner), and the network CIDR.
• Tip: Defaults to the caller IP if you don’t pass ip. Great for server-side middleware.

#POST /v1/geoip/country — Country Lookup

• Best for: Legal gating (GDPR/EU, export controls), pricing localization, content availability.
• Output: ISO country code + name, isEU, and a continent object.
• Tip: Keep it simple for edge workers; this is the fastest “allow/deny/route” decision.

#POST /v1/geoip/city — City Lookup

• Best for: Timezone-aware UX, nearest-PoP routing, language defaults, coarse analytics.
• Output: city, region, country, timezone, and loc (lat,lng).
• Tip: Combine with CDN edge headers to avoid extra hops on hot paths.

#Quick start

# ASN
curl -X POST "https://api.yeb.to/v1/geoip/asn" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "ip": "8.8.4.4" }'

# Country
curl -X POST "https://api.yeb.to/v1/geoip/country" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "ip": "1.1.1.1" }'

# City
curl -X POST "https://api.yeb.to/v1/geoip/city" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "ip": "8.8.8.8" }'

#Parameters that actually matter

#Reading & acting on responses

#ASN Lookup — interpretation

{
  "ip":  "8.8.4.4",
  "org": "Google LLC",
  "asn": 15169,
  "network": "8.8.4.0/24"
}

• org — owner name you can show in admin/audit UIs.
• asn — useful for allow/deny lists, bot heuristics, or prioritizing traffic from major ISPs/CDNs.
• network — CIDR range to cache or apply rules on (rate-limits, exemptions).

#Country Lookup — interpretation

{
  "ip": "1.1.1.1",
  "country": "AU",
  "country_name": "Australia",
  "isEU": false,
  "country_flag": "🇦🇺",
  "continent": { "code": "OC", "name": "Oceania" }
}

• country/country_name — drive content, taxes, or legal disclaimers.
• isEU — immediate GDPR-related branching without maintaining your own country list.
• continent — coarse routing or analytics bucketing.

#City Lookup — interpretation

{
  "data": {
    "ip": "8.8.8.8",
    "hostname": "dns.google",
    "city": "Mountain View",
    "region": "California",
    "country": "US",
    "loc": "37.3860,-122.0840",
    "timezone": "America/Los_Angeles",
    "country_flag": "🇺🇸",
    "emoji": "🇺🇸"
  }
}

• timezone — default scheduling UI, email send windows, or cron-like tasks per user.
• loc — approximate coordinates, good enough for nearest datacenter or store finder default.
• hostname — sometimes reveals corporate/ISP hints helpful in fraud pipelines.

#Practical recipes

• Compliance gating: If country.isEU → enable consent flows; if not, use lighter banners.
• Routing: Resolve PoP by continent.code (e.g., NA/EU/APAC) and fall back to city if ambiguous.
• Abuse control: Down-rank traffic from hosting ASNs during signup; boost residential ISPs.
• UX defaults: Use timezone to pre-fill user settings; offer override in profile.

#API Changelog