Skip to content

8. REST API Endpoints

Jump to bottom
Héctor Cabrera edited this page Jun 24, 2024 · 5 revisions

With the release of version 4.7, WordPress -finally- introduced its very own REST API:

Content endpoints provide machine-readable external access to your WordPress site with a clear, standards-driven interface, paving the way for new and innovative methods of interacting with sites through plugins, themes, apps, and beyond.

WordPress Popular Posts (4.1+) provides its own REST API endpoints so you can display your popular entries on your (web) application.

/

Get links to all other endpoints available in the API.

  • HTTP method: GET
  • URLs: /wp-json/wordpress-popular-posts/v1/ and /wp-json/wordpress-popular-posts/v2/

/v1/popular-posts

Get popular posts.

  • HTTP method: GET
  • URL: /wp-json/wordpress-popular-posts/v1/popular-posts/

Parameters

post_type

Return popular posts from specified (custom) post types (separated by comma).

  • Required: no
  • Default: "post"
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?post_type=post,page

limit

The maximum number of popular posts to return.

  • Required: no
  • Default: 10
  • Type: integer

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?limit=5

freshness

Retrieve the most popular entries published within the specified time range.

  • Required: no
  • Default: "0" (0 = disabled, 1 = enabled)
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?freshness=1

offset

An offset point for the collection.

  • Required: no
  • default: 0
  • Type: integer

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?offset=5

order_by

Set the sorting option of the popular posts.

  • Required: no
  • Default: "views" (possible values: "views", "comments")
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?order_by=comments

range

Return posts from a specified time range.

When using the value "custom" in conjunction with the parameters time_unit and time_value (see below) you can retrieve popular posts from a custom defined time range (eg. last 12 hours).

  • Required: no
  • Default: "last24hours" (possible values: "last24hours", "last7days", "last30days", "all", "custom")
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?range=last7days

time_unit

Specifies the time unit of the custom time range.

  • Required: false
  • Default: "hour" (possible values: "minute", "hour", "day", "week", "month")
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?range=custom&time_unit=hour&time_quantity=12

time_quantity

Specifies the number of time units of the custom time range.

  • Required: no
  • Default: 24
  • Type: integer

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?range=custom&time_unit=hour&time_quantity=12

pid

Post IDs to exclude from the listing (comma separated).

  • Required: no
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?pid=56,75,109

taxonomy

Include posts in a specified taxonomy.

To filter posts by taxonomy you also need to specify the term ID(s) via term_id.

  • Required: no
  • Default: "category"
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?taxonomy=post_tag&term_id=115

term_id

Taxonomy IDs, separated by comma (prefix a minus sign to exclude).

  • Required: no
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?taxonomy=post_tag&term_id=115

author

Include popular posts from author ID(s).

  • Required: no
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v1/popular-posts?author=1,3,7

/v2/views/[post_id] (GET)

Returns the views count of a given post / page / custom post type ID.

  • HTTP method: GET
  • URL: /wp-json/wordpress-popular-posts/v2/views/[post_id]

Parameters

range

The time range.

  • Required: false
  • Default: "all" (possible values: "last24hours", "last7days", "last30days", "all", "custom")
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v2/views/[post_id]?range=last24hours

time_unit

Specifies the time unit of the custom time range.

  • Required: false
  • Default: "hour" (possible values: "minute", "hour", "day", "week", "month")
  • Type: string

Usage: /wp-json/wordpress-popular-posts/v2/views/[post_id]?range=custom&time_unit=hour&time_quantity=12

time_quantity

Specifies the number of time units of the custom time range.

  • Required: no
  • Default: 24
  • Type: integer

Usage: /wp-json/wordpress-popular-posts/v2/views/[post_id]?range=custom&time_unit=hour&time_quantity=12

include_views_text

Whether to include the "views" text as part of the response (eg. 2,932 views).

  • Required: no
  • Default: 1
  • Type: integer

Usage: /wp-json/wordpress-popular-posts/v2/views/[post_id]?include_views_text=0

/v2/views/[post_id] (POST)

Updates the views count of a given post / page / custom post type ID.

  • HTTP method: POST
  • URL: /wp-json/wordpress-popular-posts/v2/views/[post_id]

Parameters

sampling

Whether to apply Data Sampling to this page view request. Default is disabled (0).

  • Required: false
  • Default: 0 (possible values: 0, 1)
  • Type: integer

sampling_rate

The sampling rate.

  • Required: false
  • Default: 100
  • Type: integer

Usage: /wp-json/wordpress-popular-posts/v2/views/[post_id]

Note that to send a POST request to this endpoint you must provide a valid nonce called '_wpnonce' either via the _wpnonce parameter or the X-WP-Nonce request header, otherwise the REST API will return an HTTP 401 Forbidden response.

Clone this wiki locally