API Documentation

GeoPry API

Extract precise geolocation data from images and videos with our powerful AI-driven API. Supports real-time streaming, batch processing, and multiple input formats.

Need help integrating?

Quick Start

Get started with GeoPry in three simple steps:

1
Get your API key
Sign up and generate your API key from the dashboard.
2
Make your first request
Send an image file or URL to our /v1/analyze endpoint.
3
Get precise coordinates
Receive latitude, longitude, address, and confidence score in the response.

Base URL

https://api.geopry.com/v1

Authentication

All API requests require authentication using your API key. Include it in the X-API-Key header:

X-API-Key: gp_live_xxxxxxxxxxxxxxxxxxxx

Security Notice

Keep your API key secure. Never expose it in client-side code or public repositories. Use environment variables for production deployments.

Endpoints

POST/v1/analyze

Analyze an image or video and extract geolocation data with real-time streaming updates.

Parameter	Type	Required	Description
`file`	File	Yes	Single image or video file (JPG, PNG, WebP, HEIC, MP4, MOV, WebM)
`files`	File[]	No	Multiple image files for batch analysis (max 3)
`url`	string	No	URL of image or video to analyze
`urls`	string[]	No	Multiple URLs for batch analysis (max 3)
`analysis_mode`	string	No	Analysis mode: "fast" (default), "agent", or "event"
`stream`	boolean	No	Enable Server-Sent Events for real-time updates (default: false)
`user_context`	string	No	Additional context hints to improve accuracy

GET/v1/usage

Get current API usage statistics and remaining request quota.

GET/v1/history

Retrieve your analysis history with pagination support.

Parameter	Type	Required	Description
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (default: 20, max: 100)

Code Examples

curl -X POST https://api.geopry.com/v1/analyze \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "analysis_mode=fast"

Real-time Streaming

Enable stream: true to receive real-time Server-Sent Events (SSE) during analysis. This provides live progress updates and intermediate results.

Event Types

processingProgress updates during analysis

branch_pointParallel analysis branches created

branch_updateIndividual branch status updates

completedFinal result with locations and remaining quota

errorError occurred during processing

Example SSE Stream

Server-Sent Events

event: processing
data: {"type":"progress","message":"Running visual analysis..."}

event: processing
data: {"type":"progress","message":"Cross-referencing geographic databases..."}

event: branch_point
data: {"type":"branch_point","branch_point":{"fork_id":"analysis_methods","branches":[{"branch_id":"visual","label":"Visual Analysis","status":"processing"},{"branch_id":"satellite","label":"Satellite Match","status":"processing"}]}}

event: branch_update
data: {"type":"branch_update","branch_id":"visual","status":"completed","message":"Found 2 candidates"}

event: completed
data: {"type":"complete","result":{"status":"success","locations":[{"latitude":48.8584,"longitude":2.2945,"address":"Eiffel Tower, Paris, France","confidence":0.95,"reasoning":"..."}],"processing_time":"12.4s","API_Requests_remaining":67}}

Response Format

JSON Response

{
  "status": "success",
  "locations": [
    {
      "latitude": 48.8584,
      "longitude": 2.2945,
      "confidence": 0.95,
      "address": "Eiffel Tower, Paris, France",
      "reasoning": "The image shows the Eiffel Tower from Trocadero gardens with characteristic iron lattice structure and surrounding architecture consistent with the 7th arrondissement of Paris."
    },
    {
      "latitude": 48.853,
      "longitude": 2.3499,
      "confidence": 0.72,
      "address": "Notre-Dame, Paris, France",
      "reasoning": "Gothic cathedral architecture and urban layout align with Notre-Dame area, though partially obscured."
    }
  ],
  "processing_time": "12.4s",
  "API_Requests_remaining": 67
}

Response Fields

locationsArray of matched locations
confidenceMatch confidence (0-1)
reasoningAI explanation for match
processing_timeTime taken (string with "s")

Contract Guarantees

locations always present on success
API_Requests_remaining is a number
processing_time has "s" suffix
status is "success" on success

Error Handling

The API uses standard HTTP status codes and returns detailed error messages:

400

Bad Request

Invalid parameters, missing required fields, or malformed request

401

Unauthorized

Invalid or missing API key

402

Payment Required

Usage limit reached - upgrade your plan

413

Payload Too Large

File exceeds 10MB limit

429

Too Many Requests

Rate limit exceeded or queue full

500

Internal Error

Server error - please retry

Rate Limits

Rate limits vary by plan. Check response headers for current usage:

X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 999

X-RateLimit-Reset: 1640995200

The API_Requests_remaining field in responses also indicates your remaining quota.

Supported Formats

Images

JPGPNGWebPHEIC

Videos

MP4MOVWebM

Maximum file size: 10MB
Maximum media items per request: 3
Use file for single uploads, files for multiple
URL input keys: url and urls