Ztrace
ZTRACE

REST API Endpoints

Ztrace Documentation

Complete reference for all Ztrace REST API endpoints. All requests require authentication via Bearer token or API key header.

Base URL

All API requests should be made to: https://api.ztrace.ai/v2

Authentication

Include your API key in every request:

Bash
# Option 1: Bearer Token
<span class="text-yellow-300">Authorization</span>: <span class="text-yellow-300">Bearer</span> zt_live_xxxxxxxxxxxxx
 
# Option 2: API Key Header
<span class="text-yellow-300">X</span>-<span class="text-yellow-300">API</span>-<span class="text-yellow-300">Key</span>: zt_live_xxxxxxxxxxxxx

Endpoints Overview

MethodEndpointDescription
POST/analyzeAnalyze single image for geolocation
GET/analyze/:idGet analysis result by ID
POST/analyze/compareCompare two images
POST/batchCreate batch processing job
GET/batch/:idGet batch job status
GET/batch/:id/resultsGet batch results (paginated)
DELETE/batch/:idCancel batch job
POST/features/extractExtract features from image
POST/webhooksCreate webhook
GET/webhooksList webhooks
GET/accountGet account info
GET/usageGet usage statistics

Complete API Reference

api-reference.ts
TypeScript
1// Ztrace REST API v2 - Complete Endpoint Reference
2 
3/**
4 * <span class="text-yellow-300">Base</span> <span class="text-yellow-300">URL</span>: https://api.<span class="text-cyan-300">ztrace</span>.<span class="text-cyan-300">ai</span>/v2
5 * 
6 * <span class="text-yellow-300">All</span> requests require authentication via:
7 * - <span class="text-yellow-300">Header</span>: <span class="text-yellow-300">Authorization</span>: <span class="text-yellow-300">Bearer</span> <API_KEY>
8 * - <span class="text-yellow-300">Or</span>: <span class="text-yellow-300">X</span>-<span class="text-yellow-300">API</span>-<span class="text-yellow-300">Key</span>: <API_KEY>
9 */
10 
11// ============================================
12// ANALYSIS ENDPOINTS
13// ============================================
14 
15/**
16 * <span class="text-yellow-300">POST</span> /analyze
17 * <span class="text-yellow-300">Analyze</span> a single image <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>><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>>for</span></span> geolocation
18 */
19<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">AnalyzeRequest</span> {
20  // Provide ONE of the following:
21  image_url?: string;      // <span class="text-yellow-300">Public</span> <span class="text-yellow-300">URL</span> to image
22  image_base64?: string;   // <span class="text-yellow-300">Base64</span> encoded image
23  // Or upload as multipart/form-data with 'image' field
24  
25  options?: {
26    model?: <span class="text-emerald-<span class="text-orange-400">400</span>">'geo-v3'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'geo-v3-turbo'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'geo-v3-precision'</span>;
27    confidence_threshold?: number;  // <span class="text-orange-400">0.<span class="text-cyan-300">0</span></span> - <span class="text-orange-400">1.<span class="text-cyan-300">0</span></span>
28    include_features?: boolean;
29    include_landmarks?: boolean;
30    include_weather?: boolean;
31    include_satellite?: boolean;
32    max_results?: number;           // <span class="text-yellow-300">For</span> multiple location candidates
33    language?: string;              // <span class="text-yellow-300">ISO</span> <span class="text-orange-400">639</span>-<span class="text-orange-400">1</span> code
34  };
35}
36 
37/**
38 * <span class="text-yellow-300">GET</span> /analyze/:id
39 * <span class="text-yellow-300">Get</span> analysis result by <span class="text-yellow-300">ID</span>
40 */
41 
42/**
43 * <span class="text-yellow-300">POST</span> /analyze/compare
44 * <span class="text-yellow-300">Compare</span> two images <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>><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>>for</span></span> location similarity
45 */
46<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">CompareRequest</span> {
47  image1_url: string;
48  image2_url: string;
49  options?: {
50    include_features?: boolean;
51  };
52}
53 
54// ============================================
55// BATCH PROCESSING
56// ============================================
57 
58/**
59 * <span class="text-yellow-300">POST</span> /batch
60 * <span class="text-yellow-300">Create</span> a <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>>new</span> batch processing job
61 */
62<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">CreateBatchRequest</span> {
63  images: <span class="text-yellow-300">Array</span><{
64    id: string;
65    url?: string;
66    base64?: string;
67  }>;
68  options?: {
69    model?: string;
70    confidence_threshold?: number;
71    priority?: <span class="text-emerald-<span class="text-orange-400">400</span>">'low'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'normal'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'high'</span>;
72    webhook_url?: string;
73    callback_headers?: <span class="text-yellow-300">Record</span><string, string>;
74  };
75}
76 
77/**
78 * <span class="text-yellow-300">GET</span> /batch/:id
79 * <span class="text-yellow-300">Get</span> batch job status
80 */
81 
82/**
83 * <span class="text-yellow-300">GET</span> /batch/:id/results
84 * <span class="text-yellow-300">Get</span> batch job <span class="text-blue-400">results</span> (paginated)
85 * <span class="text-yellow-300">Query</span> params: limit, offset, status
86 */
87 
88/**
89 * <span class="text-yellow-300">DELETE</span> /batch/:id
90 * <span class="text-yellow-300">Cancel</span> a batch job
91 */
92 
93// ============================================
94// FEATURE EXTRACTION
95// ============================================
96 
97/**
98 * <span class="text-yellow-300">POST</span> /features/extract
99 * <span class="text-yellow-300">Extract</span> specific features <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>><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>>from</span></span> an image
100 */
101<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">ExtractFeaturesRequest</span> {
102  image_url: string;
103  feature_types: <span class="text-yellow-300">Array</span><
104    <span class="text-emerald-<span class="text-orange-400">400</span>">'text'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'landmarks'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'objects'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'faces'</span> | 
105    <span class="text-emerald-<span class="text-orange-400">400</span>">'vehicles'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'architecture'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'vegetation'</span> | <span class="text-emerald-<span class="text-orange-400">400</span>">'climate'</span>
106  >;
107  options?: {
108    language?: string;
109    min_confidence?: number;
110  };
111}
112 
113// ============================================
114// WEBHOOKS
115// ============================================
116 
117/**
118 * <span class="text-yellow-300">POST</span> /webhooks
119 * <span class="text-yellow-300">Create</span> a <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>>new</span> webhook endpoint
120 */
121 
122/**
123 * <span class="text-yellow-300">GET</span> /webhooks
124 * <span class="text-yellow-300">List</span> all webhooks
125 */
126 
127/**
128 * <span class="text-yellow-300">GET</span> /webhooks/:id
129 * <span class="text-yellow-300">Get</span> webhook details
130 */
131 
132/**
133 * <span class="text-yellow-300">PATCH</span> /webhooks/:id
134 * <span class="text-yellow-300">Update</span> webhook configuration
135 */
136 
137/**
138 * <span class="text-yellow-300">DELETE</span> /webhooks/:id
139 * <span class="text-yellow-300">Delete</span> a webhook
140 */
141 
142/**
143 * <span class="text-yellow-300">POST</span> /webhooks/:id/test
144 * <span class="text-yellow-300">Send</span> a test event to webhook
145 */
146 
147// ============================================
148// ACCOUNT & USAGE
149// ============================================
150 
151/**
152 * <span class="text-yellow-300">GET</span> /account
153 * <span class="text-yellow-300">Get</span> account information
154 */
155 
156/**
157 * <span class="text-yellow-300">GET</span> /usage
158 * <span class="text-yellow-300">Get</span> <span class="text-yellow-300">API</span> usage statistics
159 * <span class="text-yellow-300">Query</span> params: start_date, end_date, granularity
160 */
161 
162/**
163 * <span class="text-yellow-300">GET</span> /api-keys
164 * <span class="text-yellow-300">List</span> <span class="text-yellow-300">API</span> keys
165 */
166 
167/**
168 * <span class="text-yellow-300">POST</span> /api-keys
169 * <span class="text-yellow-300">Create</span> <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>>new</span> <span class="text-yellow-300">API</span> key
170 */
171 
172/**
173 * <span class="text-yellow-300">DELETE</span> /api-keys/:id
174 * <span class="text-yellow-300">Revoke</span> <span class="text-yellow-300">API</span> key
175 */

Rate Limits

PlanRequests/minBatch SizeConcurrent Jobs
Free10501
Pro1005005
Enterprise1000+10,000+Unlimited

Last updated December 2025

Was this helpful?