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"

Response Format

Sample 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
}