Using WordPress ‘oembed_endpoint_url’ PHP filter

by

The oembed_endpoint_url WordPress PHP filter modifies the oEmbed endpoint URL.

Usage

add_filter( 'oembed_endpoint_url', 'my_custom_oembed_endpoint_url', 10, 3 );

function my_custom_oembed_endpoint_url( $url, $permalink, $format ) {
    // Your custom code here

    return $url;
}

Parameters

  • $url (string) – The URL to the oEmbed endpoint.
  • $permalink (string) – The permalink used for the URL query arg.
  • $format (string) – The requested response format.

More information

See WordPress Developer Resources: oembed_endpoint_url

Examples

Change oEmbed endpoint to a custom URL

Modify the oEmbed endpoint URL to use a custom URL.

add_filter( 'oembed_endpoint_url', 'change_oembed_endpoint_url', 10, 3 );

function change_oembed_endpoint_url( $url, $permalink, $format ) {
    $custom_url = 'https://my-custom-oembed-provider.com/';
    return $custom_url;
}

Add additional parameters to the oEmbed URL

Add extra parameters to the oEmbed URL, like an API key.

add_filter( 'oembed_endpoint_url', 'add_extra_params_to_oembed_url', 10, 3 );

function add_extra_params_to_oembed_url( $url, $permalink, $format ) {
    $api_key = 'your_api_key';
    $url .= '&api_key=' . $api_key;
    return $url;
}

Use a different oEmbed provider based on post type

Change the oEmbed provider based on the post type of the content being embedded.

add_filter( 'oembed_endpoint_url', 'switch_oembed_provider_based_on_post_type', 10, 3 );

function switch_oembed_provider_based_on_post_type( $url, $permalink, $format ) {
    $post_id = url_to_postid( $permalink );
    $post_type = get_post_type( $post_id );

    if ( 'custom_post_type' === $post_type ) {
        $url = 'https://custom-provider.com/';
    }
    return $url;
}

Force a specific response format

Force the oEmbed response to always be in a specific format, such as JSON.

add_filter( 'oembed_endpoint_url', 'force_oembed_response_format', 10, 3 );

function force_oembed_response_format( $url, $permalink, $format ) {
    $url = remove_query_arg( 'format', $url );
    $url = add_query_arg( 'format', 'json', $url );
    return $url;
}

Modify oEmbed URL based on custom conditions

Customize the oEmbed URL based on specific conditions, such as user role or capabilities.

add_filter( 'oembed_endpoint_url', 'modify_oembed_url_based_on_conditions', 10, 3 );

function modify_oembed_url_based_on_conditions( $url, $permalink, $format ) {
    $user = wp_get_current_user();

    if ( in_array( 'administrator', $user->roles ) ) {
        $url = add_query_arg( 'admin', '1', $url );
    }
    return $url;
}