Quickstart

1. Get an API key

Create an API key from the platform and copy it while it is visible.

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" \
  -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")

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},
        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',
    {
      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_v4_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_v2_0",
    "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. It is optional — omit it and your request routes to the current default global model, which is what we recommend for most integrations.

Model types:

Global — worldwide coverage, 1 credit per call. Returns clusters.
High Accuracy — region-specific, higher precision, 3 credits per call. Returns predictions (no clusters).
Vehicle ID — 2 credits per call.
Property — 3 credits per call.

If you do want to pin a specific model, call GET /v1/prediction/models and take the id from that response rather than hardcoding one. Ids listed there are the models being served right now; each also carries a status field. We retire older model versions from time to time, and a retired id is rejected with a 422 naming the model — so reading the id from /models (and caching it) means a deprecation never breaks your integration.

/models returns the models your account has access to. If a region you need isn't listed, contact support@geoinfer.com to request access.

top_n accepts values from 1 to 15 (default 5). Values outside that range return a 422.

Next steps

Authentication — learn about API keys and headers
Python SDK — full SDK reference
API Reference — complete endpoint documentation

Quickstart

Quickstart

1. Get an API key

2. Make your first prediction

3. Read the response

Choosing a model

Next steps

On this page