Overview

The following describes some key concepts to help you get started with KnowYourZone's API.

• Categories
• Schema
• HTTP Status Codes
• Rate Limiting

Categories

KnowYourZone has two categories of APIs:

1. Data API - Public API for anyone who wants to access to knowyourzone.xyz's data through API.
2. Admin API - Secured API for site administration purposes.

I'm currently the sole administrator of knowyourzone.xyz and thus Admin API might not be useful for you, unless if you're cloning this repository and deploying it as your own website/service. That way, you will be your site's administrator and you might want to take a look at it.

Schema

All API access is over HTTPS, and accessed from the https://knowyourzone.xyz/api host URL. All data is sent and received as JSON.

HTTP Status Codes

KnowYourZone's API attempts to return appropriate HTTP status codes for every request. Successful responses are indicated with a 200-series HTTP code while error responses are served with a non-200-series HTTP code. The following list highlights some of the common status codes.

Code	Text	Description
200	OK	The request was successful!
400	Bad Request	The request was invalid or cannot be served. A JSON response with a message field indicating the error message will be returned. This could be due to missing required fields or invalid JSON syntax (missing quotes/curly braces).
401	Unauthorized	There was a problem authenticating your request. This could be due to missing or incorrect authentication credentials. *Applicable only for the secured Admin API.
404	Not Found	The URI requested is invalid or the resource requested does not exist/available.
429	Too Many Requests	Returned when a request cannot be served due to the rate limit being exceeded. See Rate Limiting.
500	Internal Server Error	Returned when something at the server-side is broken. This is usually a temporary error and the request can be retried.

Rate Limiting

To prevent the abuse of APIs, all API requests are subject to an IP-based rate limiting. Once a rate limit is reached, any subsequent requests made by the same originating IP address will fail and the API will return an error code until enough time has passed for the call count to drop below the limit.

The returned HTTP headers of any API request show your current rate limit status:

$ curl -i -X GET https://knowyourzone.xyz/api/data/covid19/latest
> HTTP/1.1 200 OK
> Date: Thu, 06 Aug 2020 07:51:15 GMT
> X-RateLimit-Limit: 100
> X-RateLimit-Remaining: 99
> X-RateLimit-Reset: 1596701451
> ...

Header Name	Description
X-RateLimit-Limit	The maximum number of requests you're permitted to make per rate limit window.
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
X-RateLimit-Reset	The time at which the current rate limit window resets in UTC epoch seconds.

If you exceed the rate limit, an error response returns:

> HTTP/1.1 429 Too Many Requests
> Date: Thu, 06 Aug 2020 07:59:20 GMT
> X-RateLimit-Limit: 100
> X-RateLimit-Remaining: 0
> X-RateLimit-Reset: 1596701451

> {
>   "message": "Rate limit exceeded"
> }