Eign Location Intelligence

Overview

The Eign Location Intelligence API provides a standardized REST interface for computing AI-generated urban performance intelligence at the address or coordinate level.

Each request returns normalized 0–10 composite and category-specific indices across multiple urban dimensions, including Living, Transportation, Community, Nature, Education, and other infrastructure layers, derived from the aggregation of 50+ structured urban indicators.

The API is designed for real-time, enterprise-scale integration and supports global deployment with region-by-region coverage activation.

All intelligence outputs are computed live and delivered through a consistent JSON response structure.

Authentication

All endpoints under the /v1/* namespace require an API key supplied via the X-API-Key request header. Keys are prefixed with eign_live_

Request Header Example

GET /v1/index/living?address=Dubai+Marina HTTP/1.1
X-API-Key: eign_live_••••••••••••••••

OAuth-Style Scopes

Each API key is issued with a set of scopes that control access to index categories. The required scope for each endpoint is documented in the respective section.

Environments

Eign provides separate environments for development and production usage.

Production Environment

Base URL:

https://api.eign.com

• Intended for live traffic
• Subject to contractual rate limits
• SLA-backed (Tier 3+)

Sandbox Environment

Base URL:

https://sandbox.api.eign.com

• Intended for integration testing and development
• Isolated quota allocation
• Non-SLA environment
• May return simulated or limited coverage responses

Sandbox API keys are issued separately from production keys and cannot access production quotas.

Security & Operational Standards

Transport Security

All API traffic must use HTTPS.

• TLS 1.2+ is enforced
• HTTP requests are rejected
• All data is encrypted in transit
• HSTS is enabled at the edge layer

Unencrypted connections are not supported.

Authentication & Key Management

Authentication is performed via API keys supplied in the X-API-Key header.

Security controls include:

• API keys securely hashed at rest
• Multiple active keys per account supported
• Instant key revocation via dashboard
• Seamless key rotation without downtime
• Rate limits enforced per key

For enterprise deployments, OAuth 2.0 client credentials support is available upon request.

Abuse Protection & Infrastructure Monitoring

Eign infrastructure includes:

• Per-minute and per-day rate limiting
• Automated anomaly detection
• Traffic pattern monitoring
• Infrastructure-level request throttling
• Web Application Firewall (WAF) protection

Abusive behavior may result in temporary or permanent key suspension.

Data Residency & Hosting

Eign operates on region-aligned cloud infrastructure.

• Data is processed within activated coverage zones aligned to deployed markets
• Intelligence outputs are generated in real time
• No raw signal datasets are exposed
• No client-side storage or dataset creation rights are granted

Performance & Availability

Typical API performance within supported regions:

• Median latency: <200ms
• p95 latency: <350ms
• Request timeout threshold: 10 seconds

Target uptime:

• Tier 1–2: Best effort
• Tier 3+: 99%+
• Tier 4+: 99.5%+
• Tier 5: Custom enterprise SLA

Response performance metrics are available via the X-Response-Time-Ms header.

Versioning & Deprecation Policy

The API follows semantic versioning under the /v1/ namespace.

• Backward-compatible changes may occur within a major version
• Breaking changes require a new major version
• Deprecated endpoints receive a minimum 90-day notice before sunset
• Version information is included in the meta.version field

Internal Caching Clarification

The X-Cache response header reflects internal performance optimization only.

Cache status indicates whether a request was served from Eign's internal performance layer or computed fresh.

This does not grant client-side caching, storage, or dataset creation rights.

All intelligence outputs must be requested and rendered per live API call.

Rate Limits

Rate limits are enforced per API key on a rolling window. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating the number of seconds until the window resets. The current quota status is included in the meta field of every response.

Response Format

Every endpoint returns the same JSON envelope regardless of success or failure.

{
  "success": true,
  "data": {
    "index": "living",
    "overall_score": 8.4,
    "label": "Excellent",
    "coordinates": { "lat": 25.2048, "lng": 55.2708 },
    "country": "AE",
    "sub_indices": { /* category-specific fields */ },
    "generated_at": "2025-04-13T10:22:00Z"
  },
  "error": null,
  "meta": {
    "request_id": "req_01hvx...",
    "timestamp": "2025-04-13T10:22:00.431Z",
    "version": "v1",
    "quota_used_today": 42,
    "quota_limit_today": 1000,
    "quota_remaining_today": 958
  }
}

Response Fields

Score Scale

Every index and sub-index returns a normalised score in the range 0–10 accompanied by a human-readable label. Raw numeric values are always provided alongside labels to enable custom weighting in downstream applications.

Geocode Endpoint

Resolves a human-readable address string to geographic coordinates. Coordinates returned by this endpoint can be passed directly to any index endpoint via the lat/lng parameters.

Scope: geocode:read

GET /v1/location/geocode?address=Palm+Jumeirah%2C+Dubai HTTP/1.1
X-API-Key: eign_live_••••••••••••••••

{
  "success": true,
  "data": {
    "formatted_address": "Palm Jumeirah, Dubai, UAE",
    "coordinates": { "lat": 25.1124, "lng": 55.1390 },
    "country": "AE",
    "city": "Dubai"
  },
  "error": null,
  "meta": { /* quota info */ }
}

Living Index

Measures the day-to-day livability of a location, incorporating dining options, retail access, healthcare proximity, and pedestrian friendliness.

Sub-indices: dining, shopping, healthcare, walkability

Scope: living:read

GET /v1/index/living?lat=25.2048&lng=55.2708&radius=1500 HTTP/1.1
X-API-Key: eign_live_••••••••••••••••

{
  "success": true,
  "data": {
    "index": "living",
    "overall_score": 8.4,
    "label": "Excellent",
    "coordinates": { "lat": 25.2048, "lng": 55.2708 },
    "country": "AE",
    "sub_indices": {
      "dining":      { "score": 9.1, "label": "Excellent" },
      "shopping":    { "score": 8.6, "label": "Excellent" },
      "healthcare":  { "score": 7.2, "label": "Good" },
      "walkability": { "score": 6.8, "label": "Good" }
    },
    "generated_at": "2025-04-13T10:22:00Z"
  },
  "error": null,
  "meta": { "request_id": "req_01hvx...", "quota_remaining_today": 957 }
}

Transportation Index

Evaluates the connectivity of a location to public transit, road networks, and active transport infrastructure.

Sub-indices: metro_proximity, bus_stop_density, road_access, car_dependency, commute_time, bike_walk_mix

Scope: transportation:read

GET /v1/index/transportation?address=Downtown+Dubai HTTP/1.1
X-API-Key: eign_live_••••••••••••••••

{
  "success": true,
  "data": {
    "index": "transportation",
    "overall_score": 7.9,
    "label": "Good",
    "coordinates": { "lat": 25.1972, "lng": 55.2744 },
    "country": "AE",
    "sub_indices": {
      "metro_proximity":  { "score": 9.2, "label": "Excellent" },
      "bus_stop_density": { "score": 7.4, "label": "Good" },
      "road_access":      { "score": 8.8, "label": "Excellent" },
      "car_dependency":   { "score": 6.1, "label": "Good" },
      "commute_time":     { "score": 7.0, "label": "Good" },
      "bike_walk_mix":    { "score": 5.8, "label": "Fair" }
    },
    "generated_at": "2025-04-13T10:22:05Z"
  },
  "error": null,
  "meta": { "request_id": "req_02jzq...", "quota_remaining_today": 956 }
}

Community Index

Characterises the social fabric of a neighbourhood across dimensions including urban density, safety signals, amenity variety, family suitability, and ambient noise.

Sub-indices: urban_density, safety, poi_mix, family_friendliness, noise_level

Scope: community:read

GET /v1/index/community?lat=43.6532&lng=-79.3832 HTTP/1.1
X-API-Key: eign_live_••••••••••••••••

{
  "success": true,
  "data": {
    "index": "community",
    "overall_score": 7.3,
    "label": "Good",
    "coordinates": { "lat": 43.6532, "lng": -79.3832 },
    "country": "CA",
    "sub_indices": {
      "urban_density":       { "score": 8.1, "label": "Excellent" },
      "safety":              { "score": 7.5, "label": "Good" },
      "poi_mix":             { "score": 7.8, "label": "Good" },
      "family_friendliness": { "score": 6.4, "label": "Good" },
      "noise_level":         { "score": 5.9, "label": "Fair" }
    },
    "generated_at": "2025-04-13T10:22:10Z"
  },
  "error": null,
  "meta": { "request_id": "req_03kmp...", "quota_remaining_today": 955 }
}

Nature Index

Quantifies the environmental quality surrounding a location, covering green space, air quality, park accessibility, tree cover, noise pollution, and ecological risk.

Sub-indices: green_space, air_quality, park_accessibility, tree_cover, noise_pollution, environmental_risk

Scope: nature:read

GET /v1/index/nature?address=Jumeirah+Beach+Residence HTTP/1.1
X-API-Key: eign_live_••••••••••••••••

{
  "success": true,
  "data": {
    "index": "nature",
    "overall_score": 6.8,
    "label": "Good",
    "coordinates": { "lat": 25.0762, "lng": 55.1325 },
    "country": "AE",
    "sub_indices": {
      "green_space":        { "score": 5.2, "label": "Fair" },
      "air_quality":        { "score": 6.7, "label": "Good" },
      "park_accessibility": { "score": 7.9, "label": "Good" },
      "tree_cover":         { "score": 4.8, "label": "Fair" },
      "noise_pollution":    { "score": 6.1, "label": "Good" },
      "environmental_risk": { "score": 8.4, "label": "Excellent" }
    },
    "generated_at": "2025-04-13T10:22:15Z"
  },
  "error": null,
  "meta": { "request_id": "req_04rnv...", "quota_remaining_today": 954 }
}

Location Intelligence Endpoint

Returns all available indices and their full set of sub-indices for a given location in a single API call. This consolidated endpoint eliminates the need to make separate requests per index category, reducing round-trips and simplifying integration for clients that require a comprehensive urban intelligence snapshot.

Indices returned: living, transportation, community, nature

Scope: living:read, transportation:read, community:read, nature:read

GET /v1/location/intelligence?lat=25.2048&lng=55.2708 HTTP/1.1
X-API-Key: eign_live_••••••••••••••••

{
  "success": true,
  "data": {
    "coordinates": { "lat": 25.2048, "lng": 55.2708 },
    "country": "AE",
    "indices": {
      "living": {
        "overall_score": 8.4, "label": "Excellent",
        "sub_indices": { "dining": { "score": 9.1, "label": "Excellent" }, "shopping": { "score": 8.6, "label": "Excellent" }, "healthcare": { "score": 7.2, "label": "Good" }, "walkability": { "score": 6.8, "label": "Good" } }
      },
      "transportation": {
        "overall_score": 7.9, "label": "Good",
        "sub_indices": { "metro_proximity": { "score": 9.2, "label": "Excellent" }, "bus_stop_density": { "score": 7.4, "label": "Good" }, "road_access": { "score": 8.8, "label": "Excellent" }, "car_dependency": { "score": 6.1, "label": "Good" }, "commute_time": { "score": 7.0, "label": "Good" }, "bike_walk_mix": { "score": 5.8, "label": "Fair" } }
      },
      "community": {
        "overall_score": 7.3, "label": "Good",
        "sub_indices": { "urban_density": { "score": 8.1, "label": "Excellent" }, "safety": { "score": 7.5, "label": "Good" }, "poi_mix": { "score": 7.8, "label": "Good" }, "family_friendliness": { "score": 6.4, "label": "Good" }, "noise_level": { "score": 5.9, "label": "Fair" } }
      },
      "nature": {
        "overall_score": 6.8, "label": "Good",
        "sub_indices": { "green_space": { "score": 5.2, "label": "Fair" }, "air_quality": { "score": 6.7, "label": "Good" }, "park_accessibility": { "score": 7.9, "label": "Good" }, "tree_cover": { "score": 4.8, "label": "Fair" }, "noise_pollution": { "score": 6.1, "label": "Good" }, "environmental_risk": { "score": 8.4, "label": "Excellent" } }
      }
    },
    "generated_at": "2025-04-13T10:22:00Z"
  },
  "error": null,
  "meta": { "request_id": "req_05abc...", "quota_remaining_today": 953 }
}

Error Codes

All error responses follow the standard envelope with success: false and a machine-readable error.code value.

Response Headers

The following headers are included on every API response and carry useful metadata for debugging, performance monitoring, and quota management.

Azure API Management — Developer Portal

The Eign Location Intelligence API is available as a managed API product through Microsoft Azure API Management (APIM). Enterprise customers and partners can access the API via a branded developer portal, enabling self-service key provisioning, interactive API exploration, and subscription management without requiring direct contact with the Eign team.

Capabilities

Interactive API Console: Try all endpoints directly from the browser using the built-in test console, with live request and response inspection.

Self-Service Subscriptions: Developers can sign up, create subscriptions, and obtain API keys from the portal without manual approval, subject to the tier policy configured by the organisation administrator.

Product Tiers: Sandbox and production products are surfaced as separate offerings in the portal, each with their own quota policies and scope grants.

Policy Enforcement: Rate limiting, IP filtering, and JWT validation policies are applied at the APIM gateway layer before requests reach the Eign backend, providing an additional security perimeter for enterprise deployments.

Analytics Dashboard: Usage metrics, latency trends, and error rates are surfaced in the Azure APIM analytics dashboard, enabling teams to monitor consumption alongside other Azure-hosted services.

Access

The APIM developer portal is available to enterprise customers on Tier 3 and above. Provisioning is performed by the Eign integrations team. To request access, contact your account representative or email integrations@eign.com with your Azure tenant ID and the target subscription scope.

Python SDK

An official Python SDK for the Eign Location Intelligence API is available, providing a typed, idiomatic interface for all endpoints. The SDK handles authentication, request serialisation, error parsing, and retry logic out of the box, reducing integration time and boilerplate in Python-based applications.

Installation

pip install eign

Quick Start

import eign
 
client = eign.Client(api_key="eign_live_...")
 
# Single index
result = client.index.living(address="Dubai Marina")
print(result.overall_score, result.label)
 
# All indices in one call
intel = client.location.intelligence(lat=25.2048, lng=55.2708)
print(intel.indices.living.overall_score)
print(intel.indices.nature.sub_indices.air_quality.score)

SDK Features

Typed responses: All responses are returned as dataclasses with full type annotations, compatible with mypy and IDE autocompletion.

Automatic retries: Transient errors (503, network timeouts) are retried automatically with exponential backoff. Configurable via the client constructor.

Environment switching: Pass environment="sandbox" to the client to route all requests to the sandbox base URL automatically.

Async support: An async client is available via eign.AsyncClient, compatible with asyncio and frameworks such as FastAPI and aiohttp.

Python version support: Python 3.9 and above.

Resources