Predict Location
Analyze an image and return clustered geographic location predictions. Costs 1 credit per call (model-dependent).
Authorization
ApiKeyAuth API key prefixed with geo_. Manage keys at https://app.geoinfer.com/en/api.
In: header
Query Parameters
Number of location clusters to return.
Model to use. Omit it and the request routes to the current default global model — recommended, so a model deprecation never breaks your integration.
To pin a specific model, call GET /v1/prediction/models and use an id from that response; ids listed there are the ones being served. Retired ids are rejected with 422.
- Global models — worldwide coverage, 1 credit. Returns
clusters. - High Accuracy models — region-specific, 3 credits. Returns
predictions(no clusters).
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_v4_1",
"credits_consumed": 1
}
}Python SDK
The official GeoInfer Python client library — sync and async, published to PyPI.
/v1/prediction/models
Returns available prediction models and their configurations. Use this as the source of truth for `model_id`. Ids in the response are the ones being served; anything absent is retired and rejected with `422`. **Unauthenticated** — returns the `public` models. **Authenticated** — returns the models your organization has access to, including any `whitelist` models granted to it. Pass your key in the `X-GeoInfer-Key` header. Each model carries a `status` (`ready`, `down`, or `unknown`) reflecting its current serving health.