PiriAPI Docs

Rate Limiting

PiriAPI enforces rate limits to ensure fair usage and service stability. Each API key has separate rate limits for each endpoint category.

Rate Limit Categories

Rate limits are tracked independently per category. A request to Places does not affect your FTS or IP2Location quota.

Type Value	Category	Endpoints
place	Places API	GET /api/v1/places
fts	Full-Text Search	GET /api/v1/fts/search
ip_location	IP2Location	POST /api/v1/ip2location

Response Headers

Every API response includes rate limit information in the headers.

Header	Description
x-ratelimit-limit	Maximum requests allowed per time window
x-ratelimit-remaining	Number of requests remaining in the current window
x-ratelimit-reset	Unix timestamp when the current window resets
x-ratelimit-type	Category of the endpoint (`place`, `fts`, or `ip_location`)

Example

Use -I or -i with curl to inspect headers.

Request

curl -H "X-API-Key: YOUR_KEY" -I \
     "https://api-piriapi.kaanksc.com/api/v1/places?limit=1"

Response Headers

HTTP/2 200
content-type: application/json
x-ratelimit-limit: 100
x-ratelimit-remaining: 98
x-ratelimit-reset: 1787032043
x-ratelimit-type: place

Checking Remaining Quota in Code

const response = await fetch(
  "https://api-piriapi.kaanksc.com/api/v1/places?limit=1",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);

const remaining = response.headers.get("x-ratelimit-remaining");
const limit = response.headers.get("x-ratelimit-limit");
const reset = response.headers.get("x-ratelimit-reset");

console.log(`${remaining}/${limit} requests left`);
console.log(`Resets at: ${new Date(Number(reset) * 1000).toISOString()}`);

What Happens When Limited?

When you exceed the rate limit, the API returns a 429 Too Many Requests response.

{
  "error": "rate limit exceeded"
}

Wait until the reset time before making new requests, or implement exponential backoff in your application.

Usage Statistics

Track your current usage across all categories with the usages endpoint.

GET /api/v1/limiter/usages

Example

curl -H "X-API-Key: YOUR_KEY" \
     "https://api-piriapi.kaanksc.com/api/v1/limiter/usages"

Response

{
  "place": 2,
  "place_expires_at": "2026-08-18T08:42:01.384Z",
  "fts": 0,
  "fts_expires_at": null,
  "ip_location": 0,
  "ip_location_expires_at": null
}

Response Fields

Field	Description
place	Number of Places API requests made in the current window
place_expires_at	ISO 8601 timestamp when the Places usage window resets (null if no requests made)
fts	Number of Full-Text Search requests made in the current window
fts_expires_at	ISO 8601 timestamp when the FTS usage window resets
ip_location	Number of IP2Location requests made in the current window
ip_location_expires_at	ISO 8601 timestamp when the IP2Location usage window resets

Best Practices

1
Cache responses — Store results locally to avoid redundant requests for the same data.
2
Monitor headers — Check x-ratelimit-remaining to track your usage proactively.
3
Implement backoff — If you receive a 429, wait and retry with exponential delay.
4
Use limit parameter — Request only the number of results you need with ?limit=N.