---
name: ip-geolocation
description: Perform IP geolocation lookups, address geocoding, proxy/threat detection, and Geoname geographic hierarchy queries using the geo.mediashare.ro service. Use when you need to resolve an IP address to location details, geocode street addresses, detect proxies/VPNs/Tor exit nodes, or query parent/child geoname administrative regions.
---

# IP Geolocation & Geonames Skill

This skill provides instructions and examples for interacting with the geo.mediashare.ro API service running at `https://geo.mediashare.ro`.

## Authentication & Rate Limits

- **Documentation & Skills**: OpenAPI specification (`/openapi.json`) and agent skills (`/skills/*`) are public resources and are **not rate limited**.
- **Free API Access (Keyless)**: Keyless API requests for free endpoints (`/`, `/get`, `/children`, `/distance`, `/search`) are available without an API key and are rate limited to **60 requests per minute** by client IP. Unauthenticated geocoding requests rely on free providers (GeoNames, GeoPlugin, IpInfo, local MaxMind) and never call paid upstream geocoders.
- **Protected Features (API Key Required)**: The proxy & threat detection feature (`GET /proxy`, `?proxy=1`, `?check_proxy=1`), extended telecom metadata (`GET /?full=1`), and paid geocoder fallback are **not available without an API key**. Keyless requests to these features return `401 Unauthorized`.
- **Private API Access (Bearer Token)**: Send your API key in the `Authorization` header (`Authorization: Bearer <key>`) with `Accept: application/json`. Bearer token requests unlock protected features and receive higher rate limits (default 1000 req/min).

### Requesting an API Key
Need an API key for proxy detection, extended telecom intelligence, or higher rate limits?
Submit a request via the contact form at:
`https://geo.mediashare.ro/contact`

```bash
# Public keyless request (free endpoints)
curl -H "Accept: application/json" https://geo.mediashare.ro/

# Authenticated Bearer request (unlocks proxy detection & high rate limits)
curl -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" https://geo.mediashare.ro/proxy?ip=8.8.8.8
```
## Endpoints & Usage

### 1. Get Visitor IP Geolocation (`GET /`)
Retrieves geolocation metadata for the caller's IP address.

**Request:**
```bash
curl -s -H "Accept: application/json" https://geo.mediashare.ro/
```

**Response Example (`200 OK`):**
```json
{
  "status": "success",
  "country": "Romania",
  "countryCode": "RO",
  "region": "B",
  "regionName": "Bucharest",
  "city": "Bucharest",
  "zip": "010001",
  "lat": 44.4323,
  "lon": 26.1063,
  "timezone": "Europe/Bucharest",
  "isp": "Example ISP",
  "org": "Example Org",
  "as": "AS12345 Example",
  "query": "1.2.3.4"
}
```

---

### 2. Advanced Proxy & Threat Detection (`GET /proxy`) - *API Key Required*
Performs multi-layered proxy, VPN, Tor, and datacenter threat analysis for an IP address.

> **Note:** The proxy detection feature requires a valid API key. Keyless requests will return `401 Unauthorized`. If you need an API key, please request one using the contact form at `https://geo.mediashare.ro/contact`.

**Parameters:**
- `ip` *(optional)*: IP address string to analyze (defaults to caller's IP if omitted).

**Request (Authenticated):**
```bash
# Analyze a specific IP address with Bearer token
curl -s -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" "https://geo.mediashare.ro/proxy?ip=8.8.8.8"

# Analyze caller's IP address with Bearer token
curl -s -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" "https://geo.mediashare.ro/proxy"
```

**Response Example (`200 OK`):**
```json
{
  "ip": "8.8.8.8",
  "is_proxy": true,
  "is_vpn": false,
  "is_tor": false,
  "is_datacenter": true,
  "is_public_proxy": false,
  "is_residential_proxy": false,
  "is_relay": false,
  "is_crawler": false,
  "proxy_type": "datacenter",
  "risk_score": 60,
  "threat_level": "medium",
  "confidence": 0.85,
  "details": {
    "asn": 15169,
    "as_org": "Google LLC",
    "isp": "Google LLC",
    "country_code": "US",
    "datacenter_provider": "Google Cloud",
    "crawler_name": null,
    "matched_detectors": [
      "known_datacenter_heuristic"
    ],
    "detected_headers": {},
    "cached": false
  }
}
```

---

### 3. Geocode IP or Address (`GET /get`)
Geocodes a specific IP address or physical location/street address. Basic geocoding is free and rate-limited. Pass `proxy=1` to enrich the response with proxy detection data (*requires an API key*).

**Parameters:**
- `ip` *(optional)*: IP address string to geocode (defaults to client IP if omitted).
- `addr` *(optional)*: Street address or location string to geocode (takes precedence over `ip`).
- `proxy` *(optional)*: Set to `1` or `true` to attach proxy intelligence (*requires API key; returns 401 if keyless*).

**Examples:**
```bash
# Free: Geocode an IP address (keyless)
curl -s "https://geo.mediashare.ro/get?ip=8.8.8.8"

# Free: Geocode a physical address (keyless, uses free GeoNames/GeoPlugin providers)
curl -s "https://geo.mediashare.ro/get?addr=Mountain+View,+CA"

# Protected: Geocode with attached proxy intelligence (requires API key)
curl -s -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" "https://geo.mediashare.ro/get?ip=8.8.8.8&proxy=1"
```
**Response Example (`200 OK`):**
```json
{
  "city": "Mountain View",
  "county": "Santa Clara County",
  "country": "United States",
  "country_code": "US",
  "is_eu": false,
  "isEu": false,
  "languages": [
    "en-US",
    "es-US",
    "haw",
    "fr"
  ],
  "latitude": 37.3860,
  "longitude": -122.0838
}
```

---

### 4. Geoname Child Hierarchy (`GET /children`)
Fetches administrative or geographic child subdivisions for a given parent Geoname ID.

**Parameters:**
- `id` *(optional, default: `6255149`)*: Geoname ID (e.g. Earth parent ID `6255149`, continent IDs, country IDs, or administrative divisions).
- `lang` *(optional, default: `"en"`)*: Two-letter language code.

**Examples:**
```bash
# List top-level geographic regions (default parent: Earth 6255149)
curl -s "https://geo.mediashare.ro/children?id=6255149&lang=en"
```

**Response Example (`200 OK`):**
```json
[
  {
    "name": "Europe",
    "geonameId": 6255148,
    "fcodeName": "continent",
    "latitude": 48.69,
    "longitude": 9.14
  }
]
```

---

### 5. Linear Distance Calculation (`GET /distance`)
Calculates great-circle linear (Haversine) distance and compass bearing between two locations.

**Parameters:**
- `from` / `origin` *(optional)*: Origin location (coordinates `"lat,lng"`, IP address, or address string). Defaults to caller's IP address.
- `to` / `destination` *(required)*: Destination location (coordinates `"lat,lng"`, IP address, or address string).

**Examples:**
```bash
# Calculate distance between coordinate pairs
curl -s "https://geo.mediashare.ro/distance?from=44.4323,26.1063&to=45.6579,25.6012"

# Calculate distance from caller IP to an address
curl -s "https://geo.mediashare.ro/distance?to=Brasov,+Romania"
```

**Response Example (`200 OK`):**
```json
{
  "status": "success",
  "method": "haversine_great_circle",
  "origin": {
    "query": "44.4323,26.1063",
    "resolved": "44.4323, 26.1063",
    "latitude": 44.4323,
    "longitude": 26.1063
  },
  "destination": {
    "query": "45.6579,25.6012",
    "resolved": "45.6579, 25.6012",
    "latitude": 45.6579,
    "longitude": 25.6012
  },
  "distance": {
    "kilometers": 141.28,
    "miles": 87.79,
    "meters": 141280.0,
    "feet": 463517.0,
    "nautical_miles": 76.28
  },
  "bearing_degrees": 341.2
}
```


### 6. Location Search (`GET /search`)
Performs fast location search to find any location (country, city, county, etc.) and return its details including Geoname ID, feature code description, and coordinates. Supports multiple languages and warm caching.

**Parameters:**
- `q` *(required)*: Location name, country code, or query string (e.g. `Romania`, `Paris`, `RO`).
- `lang` *(optional, default: `"en"`)*: Two-letter language code for localized results (e.g. `en`, `ro`, `de`, `fr`).
- `all` *(optional, default: `false`)*: Set to `1` or `true` to return an array of multiple matching locations.
- `limit` *(optional, default: `10`)*: Maximum number of results when `all=1`.

**Examples:**
```bash
# Search for a country
curl -s "https://geo.mediashare.ro/search?q=Romania&lang=en"

# Localized search
curl -s "https://geo.mediashare.ro/search?q=Romania&lang=ro"

# Search for a city
curl -s "https://geo.mediashare.ro/search?q=Paris&lang=en"
```

**Response Example (`200 OK`):**
```json
{
  "name": "Romania",
  "geonameId": 798549,
  "fcodeName": "independent political entity",
  "latitude": 46,
  "longitude": 25
}
```

---

## Error Handling
- `401 Unauthorized`: Sent when accessing protected features (such as `/proxy` or `?proxy=1`) without an API key, or when an invalid/expired key is provided.
  ```json
  {
    "error": "Unauthorized",
    "message": "An API key is required to access the proxy detection feature."
  }
  ```
  *(To request an API key, use the contact form at `https://geo.mediashare.ro/contact`.)*
- `422 Unprocessable Entity`: Sent when invalid parameters or malformed IP addresses are supplied.
- `429 Too Many Requests`: Sent when request rate limits are exceeded (60 req/min for public IP access, custom/1000 req/min for API keys).
- `501 Not Implemented`: Sent if external IP lookup fails for `GET /`.

## OpenAPI Specification
The complete OpenAPI 3.0 specification for this API is available at:
`https://geo.mediashare.ro/openapi.json`