*/ private const CTR_BY_POSITION = array( 1 => 27.0, 2 => 15.0, 3 => 11.0, 4 => 8.0, 5 => 7.0, 6 => 5.0, 7 => 4.0, 8 => 3.0, 9 => 2.5, 10 => 2.5, ); /** * Question words, per language. * * German first because this plugin's first market is German-speaking, and * an English-only list would classify a German site's entire question * segment as "not a question" — which is worse than not having the feature. * * @return array */ public static function question_words(): array { /** * Filter the question-word list used to segment queries. * * @param array $words Lower-case words. */ return (array) apply_filters( 'airanksuite/gsc/question_words', array( // German 'was', 'wer', 'wie', 'wo', 'wann', 'warum', 'weshalb', 'wieso', 'welche', 'welcher', 'welches', 'wieviel', 'wie viel', 'wie viele', 'kann', 'darf', 'muss', 'soll', 'lohnt', 'bedeutet', 'unterschied', // English 'what', 'who', 'how', 'where', 'when', 'why', 'which', 'can', 'should', 'does', 'is', 'are', 'do', 'will', 'best', 'vs', 'versus', 'difference', 'meaning', // Spanish / French / Italian, cheaply 'que', 'como', 'cuando', 'donde', 'por que', 'comment', 'pourquoi', 'quand', 'quel', 'quelle', 'come', 'perche', 'quando', ) ); } /** * Is this query shaped like a question? */ public static function is_question( string $query ): bool { $q = trim( mb_strtolower( $query ) ); if ( '' === $q ) { return false; } if ( str_contains( $q, '?' ) ) { return true; } $words = self::question_words(); foreach ( $words as $word ) { // Anchored at the start, or as a whole word anywhere. "was" inside // "washington" is not a question, and a substring match would // classify half a travel site's queries as one. if ( str_starts_with( $q, $word . ' ' ) ) { return true; } if ( preg_match( '/(?:^|\s)' . preg_quote( $word, '/' ) . '(?:\s|$)/u', $q ) ) { return true; } } return false; } /** * Split queries into the question segment and the rest. * * @param array> $queries Query rows. * @return array */ public static function questions( array $queries ): array { $asked = array(); $totals = array( 'question' => array( 'clicks' => 0, 'impressions' => 0, 'position' => 0.0, 'n' => 0 ), 'other' => array( 'clicks' => 0, 'impressions' => 0, 'position' => 0.0, 'n' => 0 ), ); foreach ( $queries as $row ) { $bucket = self::is_question( (string) $row['key'] ) ? 'question' : 'other'; $totals[ $bucket ]['clicks'] += (int) $row['clicks']; $totals[ $bucket ]['impressions'] += (int) $row['impressions']; $totals[ $bucket ]['position'] += (float) $row['position']; ++$totals[ $bucket ]['n']; if ( 'question' === $bucket ) { $asked[] = $row; } } foreach ( $totals as $key => $t ) { $totals[ $key ]['position'] = $t['n'] > 0 ? round( $t['position'] / $t['n'], 1 ) : 0.0; $totals[ $key ]['ctr'] = $t['impressions'] > 0 ? round( 100 * $t['clicks'] / $t['impressions'], 2 ) : 0.0; } usort( $asked, static fn( $a, $b ) => $b['impressions'] <=> $a['impressions'] ); return array( 'totals' => $totals, 'rows' => array_slice( $asked, 0, 50 ), 'share' => $totals['question']['impressions'] + $totals['other']['impressions'] > 0 ? round( 100 * $totals['question']['impressions'] / ( $totals['question']['impressions'] + $totals['other']['impressions'] ), 1 ) : 0.0, ); } /** * Queries close enough to page one to be worth an afternoon. * * @param array> $queries Query rows. * @return array> */ public static function striking( array $queries, int $limit = 30 ): array { $out = array(); foreach ( $queries as $row ) { $position = (float) $row['position']; // 4 to 15: below the fold on page one, or the top of page two. // Anything above 3 is already there; anything past 15 is a // different piece of work and pretending otherwise wastes a day. if ( $position < 3.5 || $position > 15.0 ) { continue; } if ( (int) $row['impressions'] < 10 ) { continue; } $out[] = $row + array( // What one position of improvement is roughly worth, so the // list can be ordered by consequence rather than by volume. 'upside' => (int) round( ( self::expected_ctr( max( 1.0, $position - 3 ) ) - self::expected_ctr( $position ) ) / 100 * (int) $row['impressions'] ), ); } usort( $out, static fn( $a, $b ) => $b['upside'] <=> $a['upside'] ); return array_slice( $out, 0, $limit ); } /** * Results that rank and are not clicked. * * @param array> $rows Page or query rows. * @return array> */ public static function ignored( array $rows, int $limit = 30 ): array { $out = array(); foreach ( $rows as $row ) { $impressions = (int) $row['impressions']; $position = (float) $row['position']; if ( $impressions < 100 || $position > 10.5 ) { continue; } $expected = self::expected_ctr( $position ); $actual = $impressions > 0 ? 100 * (int) $row['clicks'] / $impressions : 0.0; // Half the usual rate for the position, at minimum — a small // shortfall is noise, and flagging it would bury the real cases. if ( $actual > $expected * 0.5 ) { continue; } $out[] = $row + array( 'expected_ctr' => round( $expected, 1 ), 'actual_ctr' => round( $actual, 2 ), 'lost' => (int) round( ( $expected - $actual ) / 100 * $impressions ), ); } usort( $out, static fn( $a, $b ) => $b['lost'] <=> $a['lost'] ); return array_slice( $out, 0, $limit ); } /** * Page-by-page change against the previous period of the same length. * * @param array> $now Current rows. * @param array> $previous Previous rows. * @return array{gained: array>, lost: array>} */ public static function movement( array $now, array $previous, int $limit = 15 ): array { $before = array(); foreach ( $previous as $row ) { $before[ (string) $row['key'] ] = $row; } $moved = array(); foreach ( $now as $row ) { $key = (string) $row['key']; $was = $before[ $key ] ?? null; $then = null !== $was ? (int) $was['clicks'] : 0; $diff = (int) $row['clicks'] - $then; if ( 0 === $diff ) { continue; } $moved[] = $row + array( 'before' => $then, 'change' => $diff, 'position_before' => null !== $was ? (float) $was['position'] : null, 'new' => null === $was, ); unset( $before[ $key ] ); } // Anything left in $before disappeared entirely, which is the most // important kind of loss and the one a naive diff misses. foreach ( $before as $key => $was ) { if ( (int) $was['clicks'] < 1 ) { continue; } $moved[] = array( 'key' => (string) $key, 'clicks' => 0, 'impressions' => 0, 'ctr' => 0.0, 'position' => 0.0, 'before' => (int) $was['clicks'], 'change' => -(int) $was['clicks'], 'position_before' => (float) $was['position'], 'gone' => true, ); } usort( $moved, static fn( $a, $b ) => $b['change'] <=> $a['change'] ); // Split by sign rather than taking the head and the tail of one list. // On a small site the two slices would otherwise overlap and the same // page would appear under both "gained" and "lost", which is worse // than showing nothing. $gained = array_values( array_filter( $moved, static fn( array $r ): bool => $r['change'] > 0 ) ); $lost = array_values( array_filter( $moved, static fn( array $r ): bool => $r['change'] < 0 ) ); return array( 'gained' => array_slice( $gained, 0, $limit ), 'lost' => array_slice( array_reverse( $lost ), 0, $limit ), ); } /** * Interpolated expected click-through for a fractional position. */ private static function expected_ctr( float $position ): float { if ( $position <= 1.0 ) { return self::CTR_BY_POSITION[1]; } if ( $position >= 10.0 ) { // Past the first page the curve is flat and low; a formula that // keeps decaying would imply precision that does not exist. return 1.0; } $low = (int) floor( $position ); $high = (int) ceil( $position ); $a = self::CTR_BY_POSITION[ $low ] ?? 1.0; $b = self::CTR_BY_POSITION[ $high ] ?? 1.0; $t = $position - $low; return $a + ( ( $b - $a ) * $t ); } }