MapGuessr API Service

This service provides secure API access for the MapGuessr game. You need to authenticate to use these APIs.

How to Access the API

To use the protected endpoints, include your authentication token in one of these ways:

Example using fetch:

fetch('/api/score', {
  headers: {
    'Authorization': 'Bearer ' + yourToken,
    'Content-Type': 'application/json'
  }
})

Available APIs

/api/cities

Returns a city name based on authentication status:

Example request: GET /api/cities

Example response: {"city": "New York"}

This endpoint does not require authentication (but behaves differently with valid auth).

/api/geocode?city={cityName}

Returns geocoding information for the specified city. (Requires authentication)

Example request: GET /api/geocode?city=Paris

Requires authentication

/api/mapstyle?style={styleId}

Returns the MapTiler style definition for the specified style ID. (Requires authentication)

Example request: GET /api/mapstyle?style=streets

Requires authentication

/api/user

Returns information about the currently logged in user. (Requires authentication)

Example request: GET /api/user

Example response: {"valid":true,"user":{"id":"user_id","email":"user@example.com","displayName":"User Name","role":"user"}}

Requires authentication

/api/user/email

Returns only the email of the currently logged in user. (Requires authentication)

Example request: GET /api/user/email

Example response: {"email":"user@example.com"}

Requires authentication

/api/user/name

Returns only the display name of the currently logged in user. (Requires authentication)

Example request: GET /api/user/name

Example response: {"name":"User Name"}

Requires authentication

/api/user/role

Returns only the role of the currently logged in user. (Requires authentication)

Example request: GET /api/user/role

Example response: {"role":"user"}

Requires authentication

/api/user/id

Returns only the ID of the currently logged in user. (Requires authentication)

Example request: GET /api/user/id

Example response: {"id":"user_id"}

Requires authentication

/api/score

Get or update the current user's score. (Requires authentication)

GET request: GET /api/score

GET response: {"score": 1500, "userId": "user_id", "name": "User Name", "lastUpdated": "2024-01-01T00:00:00.000Z"}

POST request: POST /api/score with body {"score": 100}

POST response: {"success": true, "previousScore": 1500, "addedScore": 100, "newTotalScore": 1600, "userId": "user_id", "name": "User Name"}

Note: POST adds the provided score to the user's existing total score.

Requires authentication

/api/leaderboard

Returns the top 3 users by total score.

Example request: GET /api/leaderboard

Example response: {"leaderboard": [{"rank": 1, "userId": "user1", "name": "Player One", "score": 2500, "lastUpdated": "2024-01-01T00:00:00.000Z"}, ...]}

This endpoint does not require authentication.

/api/logout

Logs out the current user and revokes their token. (Requires authentication)

Example request: POST /api/logout

Example response: {"success":true,"message":"Logged out successfully"}

Requires authentication