API Reference

Comprehensive reference for the Ultimate Context API.

Base URL: https://ultimate-context-api.vercel.app/v1

Request Structure

Authentication

All API requests must be authenticated using the `x-api-key` header.

x-api-key: sk_12345abcdef...

Rate Limiting

The API enforces rate limits to ensure fair usage. Limits are based on your plan tier.

TierLimit
Free100 req/min
Pro10,000 req/min

Exceeding limits will return a `429 Too Many Requests` status code.

Data Segments & Endpoints

The API returns data in "segments". You can request specific segments using the fields parameter to reduce latency and response size.

Core

IP & Location

Precise geolocation data including city, country, coordinates, and ISP information.

Available Fields

  • ip Request IP address
  • location.city City name
  • location.country Country name
  • location.timezone Timezone ID
  • location.coordinates Lat/Lon object
  • location.isp Internet Service Provider
# Request Format
GET /v1/enrich?fields=location.city,location.country,location.coordinates

// Response
{
  "location": {
    "city": "Mountain View",
    "country": "United States",
    "coordinates": {
      "lat": 37.386,
      "lon": -122.083
    }
  }
}
Context

Weather

Real-time weather conditions for the IP's location.

Available Fields

  • context.weather.temp_c Temperature (Celsius)
  • context.weather.condition Condition text
  • context.weather.humidity Humidity %
  • context.weather.wind_kph Wind speed
GET /v1/enrich?fields=context.weather

// Response
{
  "context": {
    "weather": {
      "temp_c": 22.5,
      "condition": "Partly cloudy",
      "humidity": 45
    }
  }
}
Context

Currency

Local currency information associated with the location.

Available Fields

  • context.currency.code ISO 4217 Code (e.g. USD)
  • context.currency.rate Exchange rate to USD
  • context.currency.symbol Currency symbol
GET /v1/enrich?fields=context.currency

// Response
{
  "context": {
    "currency": {
      "code": "EUR",
      "rate": 0.92,
      "symbol": "€"
    }
  }
}
Context

Holidays

Public holiday information for the location.

Available Fields

  • context.holidays.is_holiday Boolean status
  • context.holidays.holiday_name Name of holiday
GET /v1/enrich?fields=context.holidays

// Response
{
  "context": {
    "holidays": {
      "is_holiday": true,
      "holiday_name": "Christmas Day"
    }
  }
}
Context

Security

Risk analysis and security context for the IP address.

Available Fields

  • context.security.is_proxy Proxy detection
  • context.security.is_tor Tor code detection
  • context.security.risk_score 0-100 Risk Score
GET /v1/enrich?fields=context.security

// Response
{
  "context": {
    "security": {
      "is_proxy": true,
      "is_tor": false,
      "risk_score": 85
    }
  }
}
Context

Device

User agent analysis to determine device type and OS.

Available Fields

  • context.device.type 'mobile' | 'desktop'
  • context.device.os Operating System
  • context.device.browser Browser Name
GET /v1/enrich?fields=context.device

// Response
{
  "context": {
    "device": {
      "type": "desktop",
      "os": "Windows",
      "browser": "Chrome"
    }
  }
}