Developer Documentation

Villa Authority API

Programmatic access to villa quality scores, risk flags, and verification data. Built for travel platforms, property managers, and institutional investors.

Authentication

All API requests require an API key passed in the Authorization header.

curl -H "Authorization: Bearer va_your_api_key_here" \
  https://api.villaauthority.com/v1/villas/VA-98201

Never expose your API key in client-side code. Use server-side requests only.

Endpoints

GET/v1/villas/{villa_id}

Get Villa Details

Returns full villa profile including metadata and verification status.

Parameters

Name	Type	Required	Description
villa_id	string	required	Villa Authority ID (e.g. VA-98201)

Example Request

curl -H "Authorization: Bearer va_your_api_key" \
  "https://api.villaauthority.com/v1/villas/VA-98201"

Response

{
  "villa_id": "VA-98201",
  "name": "Canggu Ocean Villa",
  "location": "Canggu, Bali",
  "country": "Indonesia",
  "overall_score": 85,
  "rating_tier": "Strong",
  "confidence_level": "High",
  "verification_level": "Authority Reviewed",
  "created_at": "2024-01-15T00:00:00Z"
}

Rate Limits & Error Codes

Rate Limiting

Rate limits are enforced per API key per minute:

Free10 req/min

Professional100 req/min

InstitutionalUnlimited

Error Codes

401Invalid or missing API key

403Insufficient tier for this endpoint

404Villa not found

429Rate limit exceeded

500Internal server error

API Access Tiers

Simple, transparent pricing

Free

$0/forever

100 requests/month
Score & tier data
Public villas only

Professional

$49/per month

10,000 requests/month
Full breakdown data
Risk flags access
Priority support

Institutional

Custom/enterprise

Unlimited requests
Bulk data export
Webhook notifications
SLA guarantee
Dedicated support