API Reference

Predict Location

Analyze an image and return clustered geographic location predictions. Costs 1 credit per call (model-dependent).

POST
/v1/prediction/predict

Authorization

ApiKeyAuth
X-GeoInfer-Key<token>

API key prefixed with geo_. Manage keys at https://app.geoinfer.com/en/api.

In: header

Query Parameters

top_n?integer

Number of location clusters to return.

Default5
Range1 <= value <= 20
model_id?string

Model to use. Defaults to global_v0_1. Use GET /v1/prediction/models to list all models available to your account.

  • global_v0_1 — Global model. Worldwide coverage, 1 credit. Returns clusters.
  • High Accuracy models — region-specific, 3 credits. Returns predictions (no clusters). Requires whitelist access.
Default"global_v0_1"

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/v1/prediction/predict" \  -F file="string"
{
  "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
  }
}
Empty
Empty
Empty
Empty

Python SDK

The official GeoInfer Python client library — sync and async, published to PyPI.

/v1/prediction/models

Returns available prediction models and their configurations. **Unauthenticated** — returns only `public` models (e.g. Global). **Authenticated** — if your API key has whitelist access, the response also includes `whitelist` models such as High Accuracy region-specific models. Pass your key in the `X-GeoInfer-Key` header.