GeoData API

Project: Geo Location Info Service (RapidAPI-backed)

A lightweight service that fetches geo-location information using the RapidAPI provider geo-location-info-api.p.rapidapi.com. The project exposes simple REST endpoints (or a CLI) that your apps can call to look up information such as country, region, city, and coordinates for a given IP address or query.

---

Goals

• Provide a simple, consistent way to query geo data with one credential (RapidAPI key).
• Offer a small, cacheable API surface for your apps (server-to-server or frontend via a backend).
• Keep provider details (headers, base URL, authentication) hidden behind your own service.

---

How It Works

1. Your app calls this service (e.g., GET /geo/ip/{ip}) or uses a CLI.
2. The service forwards the request to RapidAPI using:
   • Base URL: https://geo-location-info-api.p.rapidapi.com
   • Required headers:
     • x-rapidapi-host: geo-location-info-api.p.rapidapi.com
     • x-rapidapi-key: <YOUR_RAPIDAPI_KEY>
3. The service validates inputs, handles errors, and normalizes the response shape.
4. Optional: Responses are cached to reduce latency and cost.

---

Features

• IP lookup endpoint(s) to retrieve geo-location information.
• Input validation with friendly error messages.
• Normalized response structure (consistent keys across provider changes).
• Configurable timeouts and optional in-memory caching.
• Ready for containerized deployment.

---

API Surface (proposed)

• GET /health
  • Returns service health status.
• GET /geo/ip/{ip}
  • Looks up geo data for a specific IPv4/IPv6.
  • Query params: fields (optional, comma-separated subset), refresh (bool to bypass cache).
• GET /geo/ip
  • Uses caller IP (via X-Forwarded-For or request source) when {ip} is not provided.

Notes:

• The exact RapidAPI endpoint names can vary by provider plan. This project treats RapidAPI as an upstream and focuses on a stable, provider-agnostic interface. If the provider exposes other capabilities (e.g., reverse geocoding by coordinates), you can add GET /geo/reverse?lat=..&lon=.. similarly.

---

Configuration

• Environment variables
  • RAPIDAPI_KEY (required): Your RapidAPI key for the provider.
  • RAPIDAPI_BASE_URL (default: https://geo-location-info-api.p.rapidapi.com)
  • RAPIDAPI_HOST (default: geo-location-info-api.p.rapidapi.com)
  • PORT (default: 8080)
  • CACHE_TTL_SECONDS (default: 300) — set 0 to disable caching.
  • REQUEST_TIMEOUT_MS (default: 5000)

---

Example Requests

Direct RapidAPI call (cURL)

curl -s \
  -H "x-rapidapi-host: geo-location-info-api.p.rapidapi.com" \
  -H "x-rapidapi-key: $RAPIDAPI_KEY" \
  "https://geo-location-info-api.p.rapidapi.com/ip/8.8.8.8"

Go (server snippet for forwarding)

package main

import (
  "log"
  "net/http"
  "os"
  "time"
)

func main() {
  key := os.Getenv("RAPIDAPI_KEY")
  base := os.Getenv("RAPIDAPI_BASE_URL")
  if base == "" { base = "https://geo-location-info-api.p.rapidapi.com" }

  http.HandleFunc("/geo/ip/", func(w http.ResponseWriter, r *http.Request) {
    ip := r.URL.Path[len("/geo/ip/"):]
    if ip == "" {
      http.Error(w, "missing ip", http.StatusBadRequest)
      return
    }

    req, _ := http.NewRequest("GET", base+"/ip/"+ip, nil)
    req.Header.Set("x-rapidapi-host", "geo-location-info-api.p.rapidapi.com")
    req.Header.Set("x-rapidapi-key", key)

    client := &http.Client{ Timeout: 5 * time.Second }
    resp, err := client.Do(req)
    if err != nil { http.Error(w, err.Error(), http.StatusBadGateway); return }
    defer resp.Body.Close()

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(resp.StatusCode)
    _, _ = w.Write([]byte{}) // in real code, stream/copy response body
  })

  log.Println("listening on :8080")
  log.Fatal(http.ListenAndServe(":8080", nil))
}

---

Response Shape (example)

Your service should normalize upstream data into a stable structure like:

{
  "ip": "8.8.8.8",
  "country": {
    "code": "US",
    "name": "United States"
  },
  "region": "California",
  "city": "Mountain View",
  "location": { "lat": 37.386, "lon": -122.0838 },
  "timezone": "America/Los_Angeles",
  "as": { "asn": 15169, "org": "Google LLC" },
  "source": "rapidapi:geo-location-info-api.p.rapidapi.com",
  "fetchedAt": "2025-11-23T13:12:00Z"
}

---

Error Handling

• Input validation errors return 400 with details.
• Upstream errors return 502 (bad gateway) with an upstreamStatus field.
• Timeouts mapped to 504.
• Always include a traceId for easier debugging.

---

Rate Limiting & Caching

• Apply token-bucket or fixed window limiting per IP to protect your RapidAPI quota.
• Cache success responses by IP for CACHE_TTL_SECONDS.

---

Security Considerations

• Never expose RAPIDAPI_KEY to browsers; keep calls server-side or via a backend.
• Enforce HTTPS in production.
• Add basic auth or JWT if exposing publicly.