PinPlace API Documentation

The PinPlace API allows developers to create short links for geographic locations and retrieve coordinates via simple HTTP requests.

Base URL: https://api.pinpl.ac

All POST requests require a valid API key in the header:

Authorization: Bearer <API_KEY>

API Key Types

Key Type	Example	Behavior
Demo Key	DEMO1234567890	Works for testing, returns dummy data, does not write to DB, no rate limit.
Regular Key	User-generated	Writes to DB, increments usage_count, rate-limited to 15 requests/min.
Admin / Paid Key	User-generated	No rate limit, full access.

POST /shorten

Create a short link from latitude and longitude.

URL: POST https://api.pinpl.ac/shorten

Headers:

Content-Type: application/json
Authorization: Bearer <API_KEY>

Request Body (JSON):

{
  "lat": 40.689989,
  "lng": -74.045144
}

Responses

200 OK

{
  "url": "https://pinpl.ac/abcde",
  "code": "abcde"
}

400 Bad Request
```
{
  "error": "Missing lat/lng"
}
```

401 Unauthorized

{
  "error": "API key missing or invalid"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Max 15 requests per minute"
}

500 Internal Server Error

{
  "error": "Database error",
  "message": "Error details..."
}

Notes: Demo key returns a short link but does not write to DB. Admin keys have no rate limit.

GET /resolve/{code}

Retrieve coordinates for a given short link code.

URL: GET https://api.pinpl.ac/resolve/{code}

Path Parameter:

Parameter	Type	Description
code	string	5-letter code of the short link

Responses

200 OK

{
  "latitude": 40.689989,
  "longitude": -74.045144
}

400 Bad Request
```
{
  "error": "Missing code"
}
```

401 Unauthorized

{
  "error": "API key missing or invalid"
}

404 Not Found
```
{
  "error": "Code not found"
}
```

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Max 15 requests per minute"
}

500 Internal Server Error

{
  "error": "Database error",
  "message": "Error details..."
}

Example cURL Requests

Create a short link:

curl -X POST https://api.pinpl.ac/shorten \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer DEMO1234567890" \
  -d '{"lat":40.689989,"lng":-74.045144}'

Resolve a code:

curl -H "Authorization: Bearer DEMO1234567890" https://api.pinpl.ac/resolve/abcde

Rate Limiting

Regular API keys: 15 requests per minute
Demo key: no limit (fabricated results)
Admin/Paid key: no limit

Notes

All coordinates are in WGS84.
Responses are in JSON format.
Use the demo key to test integration before using a real key.