Quickstart

Make your first GeoInfer API call in under 2 minutes.

Quickstart

1. Get an API key

Sign in and go to app.geoinfer.com/en/api. Create a key — it will start with geo_.

2. Make your first prediction

Replace geo_your_api_key_here and photo.jpg with your actual key and image path.

curl -X POST "https://api.geoinfer.com/v1/prediction/predict?top_n=5&model_id=global_v0_1" \
  -H "X-GeoInfer-Key: geo_your_api_key_here" \
  -F "file=@photo.jpg"

Install the geoinfer SDK:

pip install geoinfer
from geoinfer import GeoInfer

client = GeoInfer(api_key="geo_your_api_key_here")
result = client.predictions.predict("photo.jpg", model_id="global_v0_1")

top = result.prediction.clusters[0]
print(top.location.name, top.center.latitude, top.center.longitude)

No extra dependencies — uses the standard requests library:

pip install requests
import requests

with open("photo.jpg", "rb") as f:
    response = requests.post(
        "https://api.geoinfer.com/v1/prediction/predict",
        params={"top_n": 5, "model_id": "global_v0_1"},
        headers={"X-GeoInfer-Key": "geo_your_api_key_here"},
        files={"file": f},
    )

data = response.json()["data"]
top = data["prediction"]["clusters"][0]
print(top["location"]["name"], top["center"]["latitude"], top["center"]["longitude"])
const analyzeImage = async (imageFile, apiKey) => {
  const formData = new FormData();
  formData.append('file', imageFile);

  const response = await fetch(
    'https://api.geoinfer.com/v1/prediction/predict?top_n=5&model_id=global_v0_1',
    {
      method: 'POST',
      headers: { 'X-GeoInfer-Key': apiKey },
      body: formData,
    }
  );

  const result = await response.json();
  return result.data.prediction.clusters;
};

3. Read the response

The response shape depends on the model type.

Global models return result_type: "coordinates" with a ranked list of geographic clusters.

{
  "message_code": "success",
  "data": {
    "prediction": {
      "result_type": "coordinates",
      "clusters": [
        {
          "center": { "latitude": 40.7128, "longitude": -74.006 },
          "location": {
            "name": "New York",
            "admin1": "New York",
            "country_code": "US"
          },
          "radius_km": 15.3
        }
      ],
      "processing_time_ms": 1850
    },
    "prediction_id": "550e8400-e29b-41d4-a716-446655440000",
    "model_id": "global_v0_1",
    "credits_consumed": 1
  }
}

clusters is sorted by confidence (highest first). radius_km indicates the geographic spread of matched points — lower means tighter precision.

High accuracy models return result_type: "accuracy" with individual point predictions — no clusters. Each entry has a precise coordinate, confidence score, and rank.

{
  "message_code": "success",
  "data": {
    "prediction": {
      "result_type": "accuracy",
      "predictions": [
        {
          "latitude": 43.263,
          "longitude": -2.935,
          "confidence": 0.87,
          "rank": 1,
          "location": {
            "name": "Bilbao",
            "admin1": "Basque Country",
            "admin2": "Bizkaia",
            "country_code": "ES"
          },
          "heading_deg": 245.0
        }
      ],
      "top_prediction": {
        "latitude": 43.263,
        "longitude": -2.935,
        "confidence": 0.87,
        "rank": 1,
        "location": {
          "name": "Bilbao",
          "admin1": "Basque Country",
          "admin2": "Bizkaia",
          "country_code": "ES"
        },
        "heading_deg": 245.0
      },
      "processing_time_ms": 2300
    },
    "prediction_id": "661f9511-f3ac-52e5-b827-557766551111",
    "model_id": "pais_vasco_v0_1",
    "credits_consumed": 3
  }
}

top_prediction is a convenience field — the same as predictions[0]. heading_deg is the estimated camera heading in degrees.

Choosing a model

The model_id parameter controls which model runs. Two types are available:

  • Global (global_v0_1) — worldwide coverage, 1 credit per call. Returns clusters.
  • High Accuracy — region-specific, higher precision, 3 credits per call. Returns predictions (no clusters). Requires whitelist access.

Use GET /v1/prediction/models to list all models available to your account. Contact support@geoinfer.com to request access to High Accuracy models.

Next steps

Introduction

GeoInfer is an AI-powered image geolocation API. Upload any photo and receive clustered location predictions — no GPS, EXIF, or metadata required.

Authentication

How to authenticate requests to the GeoInfer API using API keys.

On this page

Quickstart1. Get an API key2. Make your first prediction3. Read the responseChoosing a modelNext steps