GeoSpy API Documentation

Overview

The GeoSpy API offers a RESTful API that enables clients to predict geographical locations based on image content. The service utilizes advanced machine learning models to analyze the characteristics of the image and predict potential geographical coordinates where the image might have been taken. Users have the option to receive raw predictions or clustered predictions to find the most probable locations.

Image

Geo-localization and Classification

• URL: /
• Method: POST
• Content-Type: application/json
• Authentication: API Key required in the request payload.

Request Parameters

Parameter	Type	Description
image	string	Base64-encoded string of the image.
key	string	Your GeoSpy API key.
top_k	integer	Optional. The number of top predictions to return. Default is 5.
use_classification	boolean	Optional. Set to true to enable image classification. Default is false.
anti_cluster	boolean	Optional. Set to true to apply anti-clustering for geo-predictions. Default is false.

Response

• Content-Type: application/json

Successful Response

• Status Code: 200

• Body:

  Code
   
  {
    "status": 200,
    "message": "Success",
    "geo_predictions": [
      {
        "coordinates": [13.72344970703125, 100.53968811035156],
        "score": 0.018296463415026665,
        "similarity_score_1km": 0.914715570467953
      },
      {
        "coordinates": [13.724499702453613, 100.54000091552734],
        "score": 0.01827954687178135,
        "similarity_score_1km": 0.9138698427907519
      },
      {
        "coordinates": [13.72487735748291, 100.54157257080078],
        "score": 0.018260624259710312,
        "similarity_score_1km": 0.912923823469822
      },
      {
        "coordinates": [13.721040725708008, 100.52730560302734],
        "score": 0.01798492670059204,
        "similarity_score_1km": 0.8991405668729009
      },
      {
        "coordinates": [13.72313117980957, 100.51982879638672],
        "score": 0.016850670799613,
        "similarity_score_1km": 0.8424344423073971
      }
    ]
  }

  • geo_predictions: An array of objects, each containing:
    • coordinates: An array with two elements, latitude and longitude.
    • score: A float indicating the similarity score between the image features and the predicted location.
  • image_classifications: An array of objects, each containing: - class: The classification category of the image. - score: The probability score for the classification.

Error Response

• Status Code: Non-200 HTTP codes
• Body:{ "status": code, "message": "error message" }

Usage Example

Request

Code
 
{
  "image": "base64-encoded-image-string",
  "key": "ty5dfr3w-dbd2-4fea-b224-d44321d4bdbc",
  "top_k": 5,
  // optional
  "use_classification": false,
  //optional
  "anti_cluster": false
}

Response

Code
 
{
  "status": 200,
  "message": "Success",
  "geo_predictions": [
    {
      "coordinates": [13.72344970703125, 100.53968811035156],
      "score": 0.018296463415026665
    }
  ]
}

---

Additional Information

• The use_classification parameter is in beta and may affect response times.
• Scores for geo-predictions should not be compared across different images but can be used to gauge the relative accuracy of predictions for the same image.
• The anti_cluster feature is designed to provide broader geographic predictions when specific location features are ambiguous. This feature is also in beta.

Please replace the ENDPOINT_URL and API_KEY in the example with the actual values provided to you.

Rate Limiting

• The GeoSpy API Supports up to 6 requests a second
• We do allow burst of up to 100 requests a second but if you make too many request a second you may get a disconnect