diff --git a/app/Http/Controllers/Api/ApiAnalyticsController.php b/app/Http/Controllers/Api/ApiAnalyticsController.php index 8e4bc7e..2efc4c2 100644 --- a/app/Http/Controllers/Api/ApiAnalyticsController.php +++ b/app/Http/Controllers/Api/ApiAnalyticsController.php @@ -8,7 +8,7 @@ use App\Helpers\StatsHelper; class ApiAnalyticsController extends ApiController { public function lookupLinkStats (Request $request, $stats_type=false) { - $response_type = $request->input('response_type'); + $response_type = $request->input('response_type') ?: 'json'; if ($response_type != 'json') { abort(401, 'Only JSON-encoded data is available for this endpoint.'); diff --git a/docs/css/base.css b/docs/css/base.css index 7a4af72..3183ecd 100644 --- a/docs/css/base.css +++ b/docs/css/base.css @@ -11,3 +11,9 @@ img { width: auto !important; height: auto !important; } + +code:not(.hljs) { + /* Do not wrap pre-formatted code snippets */ + word-wrap: break-word; + white-space: normal; +} diff --git a/docs/developer-guide/api.md b/docs/developer-guide/api.md index ccad048..c7f854b 100644 --- a/docs/developer-guide/api.md +++ b/docs/developer-guide/api.md @@ -29,6 +29,9 @@ The Polr API will reply in `plain_text` or `json`. The response type can be set by providing the `response_type` argument to the request. If not provided, the response type will default to `plain_text`. +Data endpoints will only return JSON-formatted data and will default to `json` if no +`response_type` is provided. + Example `json` responses: ``` { @@ -72,6 +75,7 @@ Arguments: Response: A JSON or plain text representation of the shortened URL. Example: GET `http://example.com/api/v2/action/shorten?key=API_KEY_HERE&url=https://google.com&custom_ending=CUSTOM_ENDING&is_secret=false` + Response: ``` { @@ -95,6 +99,7 @@ Arguments: Remember that the `url` argument must be URL encoded. Example: GET `http://example.com/api/v2/action/lookup?key=API_KEY_HERE&url_ending=2` + Response: ``` { @@ -103,6 +108,77 @@ Response: } ``` +### /api/v2/data/link +Arguments: + + - `url_ending`: the link ending for the URL to look up. (e.g `5ga`) + - `left_bound`: left date bound (e.g `2017-02-28 22:41:43`) + - `right_bound`: right date bound (e.g `2017-03-13 22:41:43`) + - `stats_type`: the type of data to fetch + - `day`: click counts for each day from `left_bound` to `right_bound` + - `country`: click counts per country + - `referer`: click counts per referer + +The dates must be formatted for the `strtotime` PHP function and must be parsable by Carbon. +By default, this API endpoint will only allow users to fetch a maximum of 365 days of data. This setting +can be modified in the `.env` configuration file. + +An API key granted to a regular user can only fetch data for their own links. +Admins can fetch data for any link. + +Response: A JSON representation of the requested analytics data. + +Example: GET `http://example.com/api/v2/data/link?stats_type=day&key=API_KEY_HERE&url_ending=5gk&response_type=json&left_bound=2017-02-28%2022:41:43&right_bound=2017-03-13%2022:21:43` + +Response: +``` +{ + "action":"data_link_day", + "result": { + "url_ending":"5gk", + "data": [ + {"x":"2017-03-10","y":42}, + {"x":"2017-03-11","y":1}, + {"x":"2017-03-12","y":5} + ] + } +} +``` + +Example: GET `http://example.com/api/v2/data/link?stats_type=country&key=API_KEY_HERE&url_ending=5gk&response_type=json&left_bound=2017-02-28%2022:41:43&right_bound=2017-03-13%2022:21:43` + +Response: +``` +{ + "action":"data_link_day", + "result": { + "url_ending":"5gk", + "data": [ + {"label":"FR","clicks":1}, + {"label":"US","clicks":6}, + {"label":"CA","clicks":41} + ] + } +} +``` + +Example: GET `http://example.com/api/v2/data/link?stats_type=country&key=API_KEY_HERE&url_ending=5gk&response_type=json&left_bound=2017-02-28%2022:41:43&right_bound=2017-03-13%2022:21:43` + +Response: +``` +{ + "action":"data_link_day", + "result": { + "url_ending":"5gk", + "data": [ + {"label":"Direct","clicks":6}, + {"label":"reddit.com","clicks":12}, + {"label":"facebook.com","clicks":30} + ] + } +} +``` + ## HTTP Error Codes The API will return an error code if your request was malformed or another error occured while processing your request. @@ -152,4 +228,5 @@ Example `plain_text` error response: ## Testing the API -You may test your integrations on http://demo.polr.me with the credentials "demo-admin"/"demo-admin". Keep in mind the instance is only a demo and may be cleared at any time. +You may test your integrations on http://demo.polr.me with the credentials "demo-admin"/"demo-admin". +The demo instance is reset every day.