Data Models & Types

1// Ztrace API Data Models & TypeScript Types
2 
3// Core Analysis Result
4<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">AnalysisResult</span> {
5  id: string;
6  status: <span class="text-emerald-<span class="text-orange-400">400</span>">'pending'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'processing'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'completed'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'failed'</span>;
7  created_at: string;
8  completed_at?: string;
9  processing_time_ms?: number;
10  
11  // Location data
12  location: <span class="text-yellow-300">Location</span>;
13  place_name: string;
14  country: string;
15  country_name: string;
16  region?: string;
17  city?: string;
18  
19  // Confidence metrics
20  confidence: number;
21  confidence_breakdown: <span class="text-yellow-300">ConfidenceBreakdown</span>;
22  
23  // Detected features
24  features: string[];
25  feature_details: <span class="text-yellow-300">FeatureDetail</span>[];
26  
27  // Optional enrichments
28  landmarks?: <span class="text-yellow-300">Landmark</span>[];
29  weather?: <span class="text-yellow-300">WeatherData</span>;
30  satellite_match?: <span class="text-yellow-300">SatelliteMatch</span>;
31  
32  // Metadata
33  model_version: string;
34  request_id: string;
35}
36 
37<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">Location</span> {
38  lat: number;
39  lng: number;
40  accuracy_m: number;
41  confidence: number;
42  bounds?: {
43    north: number;
44    south: number;
45    east: number;
46    west: number;
47  };
48  altitude_m?: number;
49}
50 
51<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">ConfidenceBreakdown</span> {
52  visual_features: number;
53  text_recognition: number;
54  landmark_matching: number;
55  satellite_correlation: number;
56  overall: number;
57}
58 
59<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">FeatureDetail</span> {
60  <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>type</span>: <span class="text-yellow-300">FeatureType</span>;
61  value: string;
62  confidence: number;
63  bounding_box?: <span class="text-yellow-300">BoundingBox</span>;
64  metadata?: <span class="text-yellow-300">Record</span><string, <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>any</span>>;
65}
66 
67<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>type</span> <span class="text-yellow-300">FeatureType</span> = 
68  | <span class="text-emerald-<span class="text-orange-400">400</span>">'landmark'</span>
69  | <span class="text-emerald-<span class="text-orange-400">400</span>">'text'</span>
70  | <span class="text-emerald-<span class="text-orange-400">400</span>">'signage'</span>
71  | <span class="text-emerald-<span class="text-orange-400">400</span>">'architecture'</span>
72  | <span class="text-emerald-<span class="text-orange-400">400</span>">'vegetation'</span>
73  | <span class="text-emerald-<span class="text-orange-400">400</span>">'vehicle'</span>
74  | <span class="text-emerald-<span class="text-orange-400">400</span>">'infrastructure'</span>
75  | <span class="text-emerald-<span class="text-orange-400">400</span>">'terrain'</span>
76  | <span class="text-emerald-<span class="text-orange-400">400</span>">'climate_indicator'</span>
77  | <span class="text-emerald-<span class="text-orange-400">400</span>">'cultural_marker'</span>;
78 
79<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">Landmark</span> {
80  id: string;
81  name: string;
82  <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>type</span>: string;
83  location: <span class="text-yellow-300">Location</span>;
84  distance_m: number;
85  bearing_deg: number;
86  confidence: number;
87  wikipedia_url?: string;
88  image_url?: string;
89}
90 
91<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">BoundingBox</span> {
92  x: number;
93  y: number;
94  width: number;
95  height: number;
96}
97 
98// Batch Processing Types
99<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">BatchJob</span> {
100  id: string;
101  status: <span class="text-emerald-<span class="text-orange-400">400</span>">'queued'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'processing'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'completed'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'failed'</span>;
102  created_at: string;
103  started_at?: string;
104  completed_at?: string;
105  total_count: number;
106  completed_count: number;
107  failed_count: number;
108  results_url?: string;
109}
110 
111<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">BatchResult</span> {
112  image_id: string;
113  success: boolean;
114  result?: <span class="text-yellow-300">AnalysisResult</span>;
115  error?: <span class="text-yellow-300">ErrorDetail</span>;
116}
117 
118// Error Types
119<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">ErrorDetail</span> {
120  code: string;
121  message: string;
122  details?: <span class="text-yellow-300">Record</span><string, <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>any</span>>;
123}
124 
125// Webhook Events
126<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>type</span> <span class="text-yellow-300">WebhookEvent</span> = 
127  | <span class="text-emerald-<span class="text-orange-400">400</span>">'analysis.<span class="text-cyan-300">started</span>'</span>
128  | <span class="text-emerald-<span class="text-orange-400">400</span>">'analysis.<span class="text-cyan-300">completed</span>'</span>
129  | <span class="text-emerald-<span class="text-orange-400">400</span>">'analysis.<span class="text-cyan-300">failed</span>'</span>
130  | <span class="text-emerald-<span class="text-orange-400">400</span>">'batch.<span class="text-cyan-300">started</span>'</span>
131  | <span class="text-emerald-<span class="text-orange-400">400</span>">'batch.<span class="text-cyan-300">progress</span>'</span>
132  | <span class="text-emerald-<span class="text-orange-400">400</span>">'batch.<span class="text-cyan-300">completed</span>'</span>
133  | <span class="text-emerald-<span class="text-orange-400">400</span>">'quota.<span class="text-cyan-300">warning</span>'</span>
134  | <span class="text-emerald-<span class="text-orange-400">400</span>">'quota.<span class="text-cyan-300">exceeded</span>'</span>;
135 
136<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>interface</span> <span class="text-yellow-300">WebhookPayload</span> {
137  event: <span class="text-yellow-300">WebhookEvent</span>;
138  timestamp: string;
139  data: <span class="text-yellow-300">Record</span><string, <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>any</span>>;
140  request_id: string;
141}