IP Cow Geo Proxy

A Cloudflare Worker that acts as a secure proxy for the ipstack API. This service helps power the geolocation features of ipcow.com by hiding the API key and providing CORS support.

Features

  • Secure API Key Storage: The IPSTACK_KEY is stored as a Cloudflare Worker secret, preventing it from being exposed in client-side code.
  • Dual-Stack Support: Can resolve the visitor’s connecting IP (CF-Connecting-IP) or accept an explicit IP address via query parameter (useful for getting IPv4 location when the client connects via IPv6).
  • CORS Handling: Sends appropriate headers to allow usage from the ipcow.com frontend.
  • Error Handling: Graceful fallback and error messaging if the upstream API fails.

Usage

Endpoint

GET https://geo.ipcow.com/

Query Parameters

Parameter Type Description
xy——- ——– ————-
ip string (Optional) The specific IP address to look up. If omitted, the worker uses CF-Connecting-IP.
_ number (Optional) Cache-busting timestamp (ignored by logic, but useful for clients).

Examples

1. Get location of the current visitor:

GET https://geo.ipcow.com/

2. Get location of a specific IP:

GET https://geo.ipcow.com/?ip=8.8.8.8

Setup & Deployment

Prerequisites

Local Development

  1. Clone the repository: 
    git clone <repository-url>
cd ipcow-geo-proxy

  2. Install dependencies (if applicable): (Currently, this is a dependency-free single file worker)

  3. Run locally: 
    wrangler dev

Configuration

You must set the IPSTACK_KEY secret in your Cloudflare Worker environment.

Using Wrangler:

wrangler secret put IPSTACK_KEY
# Enter your ipstack API key when prompted

Using Cloudflare Dashboard:

  1. Go to Workers & Pages.
  2. Select your worker (ipcow-geo-proxy).
  3. Go to Settings > Variables and Secrets.
  4. Add IPSTACK_KEY.

Deployment

Deploy to Cloudflare Workers:

wrangler deploy

API Response

The response mirrors the ipstack API JSON format, with standard HTTP status codes.

Sample Success Response:

{
  "ip": "134.201.250.155",
  "type": "ipv4",
  "continent_code": "NA",
  "continent_name": "North America",
  "country_code": "US",
  "country_name": "United States",
  "region_code": "CA",
  "region_name": "California",
  "city": "Los Angeles",
  "zip": "90013",
  "latitude": 34.0453,
  "longitude": -118.2413,
  "location": {
    "geoname_id": 5368361,
    "capital": "Washington D.C.",
    "languages": [
      {
        "code": "en",
        "name": "English",
        "native": "English"
      }
    ],
    "country_flag": "https://assets.ipstack.com/flags/us.svg",
    "country_flag_emoji": "🇺🇸",
    "country_flag_emoji_unicode": "U+1F1FA U+1F1F8",
    "calling_code": "1",
    "is_eu": false
  }
}

License

This project is part of the IP Cow ecosystem.