# 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:**
  ```json
  {
    "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

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

### Response

```json
{
  "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