API Documentation
v1Access DesertDetector's service desert analysis, demand aggregation, and market intelligence data programmatically through our REST API.
1. Get an API Key
API access requires a Professional plan or higher. Create your key from the API Keys page.
2. Authenticate Requests
Include your API key in the Authorization header:
Authorization: Bearer dd_your_api_key_here
3. Make Your First Request
curl -H "Authorization: Bearer dd_your_api_key" \ https://desertdetec.com/api/v1/analyze/90210
| Plan | Monthly Calls | Rate Limit | Endpoints |
|---|---|---|---|
| Professional | 1,000 | 10 req/min | analyze, demand, opportunities, leaderboard |
| Enterprise | 10,000 | 60 req/min | All endpoints including reports |
| Municipal | Unlimited | 120 req/min | All endpoints + custom |
Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.
Endpoints
/api/v1/analyze/:zipCodestarter+Run AI service desert analysis for a zip code. Returns service gaps, demographics, and opportunity scores.
Parameters
| Name | Type | In | Description |
|---|---|---|---|
| zipCode | string | path | 5-digit US zip code |
Example Response
{
"zipCode": "90210",
"serviceGaps": [
{
"serviceName": "Pet Grooming",
"category": "Pet Services",
"demandScore": 87,
"nearestProviderMiles": 5.2,
"estimatedAnnualRevenue": 185000
}
],
"demographics": {
"population": 21000,
"medianIncome": 125000,
"medianAge": 42
},
"overallScore": 82,
"analyzedAt": "2026-03-19T02:50:00Z"
}/api/v1/demand/:zipCodeprofessional+Get aggregated demand data including pledge totals, service requests, and threshold progress.
Parameters
| Name | Type | In | Description |
|---|---|---|---|
| zipCode | string | path | 5-digit US zip code |
Example Response
{
"zipCode": "90210",
"totalPledged": 42500,
"pledgeCount": 187,
"threshold": 50000,
"progress": 85,
"topServices": [
{ "service": "Bakery", "pledged": 18500, "pledgers": 72 },
{ "service": "Pet Grooming", "pledged": 12000, "pledgers": 55 }
]
}/api/v1/opportunitiesprofessional+List top business opportunities across all analyzed neighborhoods, ranked by opportunity score.
Parameters
| Name | Type | In | Description |
|---|---|---|---|
| limit | number | query | Max results (default 20, max 100) |
| minScore | number | query | Minimum opportunity score (0-100) |
| category | string | query | Filter by service category |
Example Response
{
"opportunities": [
{
"zipCode": "90210",
"service": "Pet Grooming",
"score": 87,
"pledged": 52000,
"estimatedRevenue": 185000,
"thresholdReached": true
}
],
"total": 142,
"page": 1
}/api/v1/leaderboardstarter+Get the top neighborhoods by pledge activity and demand.
Parameters
| Name | Type | In | Description |
|---|---|---|---|
| limit | number | query | Max results (default 10, max 50) |
Example Response
{
"neighborhoods": [
{
"zipCode": "90210",
"totalPledged": 125000,
"pledgeCount": 423,
"topService": "Bakery",
"analysisCount": 12
}
]
}/api/v1/reports/:reportIdenterprise+Retrieve a purchased premium report by ID.
Parameters
| Name | Type | In | Description |
|---|---|---|---|
| reportId | number | path | Report ID |
Example Response
{
"id": 42,
"zipCode": "90210",
"tier": "professional",
"status": "completed",
"content": { ... },
"generatedAt": "2026-03-19T02:50:00Z"
}| Code | Meaning | Resolution |
|---|---|---|
| 401 | Invalid or missing API key | Check your Authorization header |
| 403 | Insufficient plan for endpoint | Upgrade your subscription plan |
| 404 | Resource not found | Verify the zip code or resource ID |
| 429 | Rate limit exceeded | Wait and retry, or upgrade plan |
| 500 | Internal server error | Contact support |