> */ public static function types(): array { return array( __( 'General', 'ai-rank-suite' ) => array( 'Organization' => __( 'Organization', 'ai-rank-suite' ), 'Corporation' => __( 'Corporation', 'ai-rank-suite' ), 'OnlineBusiness' => __( 'Online business', 'ai-rank-suite' ), 'OnlineStore' => __( 'Online store', 'ai-rank-suite' ), 'LocalBusiness' => __( 'Local business', 'ai-rank-suite' ), 'Person' => __( 'Person / sole trader', 'ai-rank-suite' ), 'ProfessionalService' => __( 'Professional service', 'ai-rank-suite' ), 'NGO' => __( 'Non-profit / NGO', 'ai-rank-suite' ), 'GovernmentOrganization' => __( 'Government body', 'ai-rank-suite' ), ), __( 'Health', 'ai-rank-suite' ) => array( 'MedicalOrganization' => __( 'Medical organization', 'ai-rank-suite' ), 'Physician' => __( 'Doctor / practice', 'ai-rank-suite' ), 'Dentist' => __( 'Dentist', 'ai-rank-suite' ), 'Hospital' => __( 'Hospital / clinic', 'ai-rank-suite' ), 'Pharmacy' => __( 'Pharmacy', 'ai-rank-suite' ), 'VeterinaryCare' => __( 'Veterinary practice', 'ai-rank-suite' ), 'PhysicalTherapy' => __( 'Physiotherapy', 'ai-rank-suite' ), 'Optician' => __( 'Optician', 'ai-rank-suite' ), 'HealthClub' => __( 'Gym / health club', 'ai-rank-suite' ), ), __( 'Professional', 'ai-rank-suite' ) => array( 'LegalService' => __( 'Law firm', 'ai-rank-suite' ), 'Attorney' => __( 'Attorney', 'ai-rank-suite' ), 'Notary' => __( 'Notary', 'ai-rank-suite' ), 'AccountingService' => __( 'Accountant / tax adviser', 'ai-rank-suite' ), 'FinancialService' => __( 'Financial service', 'ai-rank-suite' ), 'InsuranceAgency' => __( 'Insurance agency', 'ai-rank-suite' ), 'RealEstateAgent' => __( 'Real estate agency', 'ai-rank-suite' ), 'EmploymentAgency' => __( 'Recruitment agency', 'ai-rank-suite' ), 'ArchitectAndDesigner' => __( 'Architect / designer', 'ai-rank-suite' ), 'ConsultingService' => __( 'Consultancy', 'ai-rank-suite' ), ), __( 'Trades & home', 'ai-rank-suite' ) => array( 'HomeAndConstructionBusiness' => __( 'Construction & home services', 'ai-rank-suite' ), 'Plumber' => __( 'Plumber', 'ai-rank-suite' ), 'Electrician' => __( 'Electrician', 'ai-rank-suite' ), 'RoofingContractor' => __( 'Roofer', 'ai-rank-suite' ), 'HVACBusiness' => __( 'Heating & air conditioning', 'ai-rank-suite' ), 'Locksmith' => __( 'Locksmith', 'ai-rank-suite' ), 'MovingCompany' => __( 'Removals', 'ai-rank-suite' ), 'HousePainter' => __( 'Painter & decorator', 'ai-rank-suite' ), 'GeneralContractor' => __( 'General contractor', 'ai-rank-suite' ), ), __( 'Retail & food', 'ai-rank-suite' ) => array( 'Store' => __( 'Shop', 'ai-rank-suite' ), 'ClothingStore' => __( 'Clothing store', 'ai-rank-suite' ), 'ElectronicsStore' => __( 'Electronics store', 'ai-rank-suite' ), 'FurnitureStore' => __( 'Furniture store', 'ai-rank-suite' ), 'JewelryStore' => __( 'Jewellery store', 'ai-rank-suite' ), 'GroceryStore' => __( 'Grocery store', 'ai-rank-suite' ), 'Restaurant' => __( 'Restaurant', 'ai-rank-suite' ), 'CafeOrCoffeeShop' => __( 'Café', 'ai-rank-suite' ), 'Bakery' => __( 'Bakery', 'ai-rank-suite' ), 'BarOrPub' => __( 'Bar / pub', 'ai-rank-suite' ), 'FastFoodRestaurant' => __( 'Fast food', 'ai-rank-suite' ), ), __( 'Travel & auto', 'ai-rank-suite' ) => array( 'Hotel' => __( 'Hotel', 'ai-rank-suite' ), 'BedAndBreakfast' => __( 'B&B / guest house', 'ai-rank-suite' ), 'Resort' => __( 'Resort', 'ai-rank-suite' ), 'TravelAgency' => __( 'Travel agency', 'ai-rank-suite' ), 'AutoDealer' => __( 'Car dealership', 'ai-rank-suite' ), 'AutoRepair' => __( 'Garage / car repair', 'ai-rank-suite' ), 'AutoRental' => __( 'Car rental', 'ai-rank-suite' ), 'GasStation' => __( 'Filling station', 'ai-rank-suite' ), ), __( 'Media & education', 'ai-rank-suite' ) => array( 'NewsMediaOrganization' => __( 'News publisher', 'ai-rank-suite' ), 'EducationalOrganization' => __( 'School / academy', 'ai-rank-suite' ), 'CollegeOrUniversity' => __( 'College / university', 'ai-rank-suite' ), 'LibrarySystem' => __( 'Library', 'ai-rank-suite' ), 'SportsOrganization' => __( 'Sports club', 'ai-rank-suite' ), 'PerformingGroup' => __( 'Performing group', 'ai-rank-suite' ), 'EntertainmentBusiness' => __( 'Entertainment venue', 'ai-rank-suite' ), ), __( 'Beauty & wellbeing', 'ai-rank-suite' ) => array( 'BeautySalon' => __( 'Beauty salon', 'ai-rank-suite' ), 'HairSalon' => __( 'Hairdresser', 'ai-rank-suite' ), 'DaySpa' => __( 'Day spa', 'ai-rank-suite' ), 'NailSalon' => __( 'Nail salon', 'ai-rank-suite' ), 'TattooParlor' => __( 'Tattoo studio', 'ai-rank-suite' ), 'ChildCare' => __( 'Childcare', 'ai-rank-suite' ), ), ); } /** * Flat list of valid type values, for REST validation. * * @return list */ public static function type_values(): array { $out = array(); foreach ( self::types() as $group ) { $out = array_merge( $out, array_keys( $group ) ); } return array_values( array_unique( $out ) ); } /** * Registration identifiers, grouped by the market that asks for them. * * A German buyer expects a Handelsregister number and a USt-IdNr; a GCC * buyer expects a commercial registration and a TRN; a US buyer expects an * EIN and a DUNS. Offering all of them and labelling them by region is the * difference between a form somebody fills in and a form somebody skips. * * @return array */ public static function identifiers(): array { return array( 'vat_id' => array( 'label' => __( 'VAT number', 'ai-rank-suite' ), 'prop' => 'vatID', 'region' => 'eu', 'hint' => __( 'USt-IdNr / TVA / BTW — e.g. DE123456789', 'ai-rank-suite' ), ), 'tax_id' => array( 'label' => __( 'Tax number', 'ai-rank-suite' ), 'prop' => 'taxID', 'region' => 'global', 'hint' => __( 'EIN in the US, Steuernummer in Germany, TRN in the UAE.', 'ai-rank-suite' ), ), 'reg_id' => array( 'label' => __( 'Company register number', 'ai-rank-suite' ), 'prop' => 'identifier', 'region' => 'eu', 'hint' => __( 'Handelsregister (HRB), Companies House, RCS, KvK.', 'ai-rank-suite' ), ), 'duns' => array( 'label' => __( 'DUNS number', 'ai-rank-suite' ), 'prop' => 'duns', 'region' => 'us', 'hint' => __( 'Dun & Bradstreet — used by US procurement and Google Merchant.', 'ai-rank-suite' ), ), 'lei' => array( 'label' => __( 'LEI code', 'ai-rank-suite' ), 'prop' => 'leiCode', 'region' => 'global', 'hint' => __( 'Legal Entity Identifier — 20 characters, required for regulated finance.', 'ai-rank-suite' ), ), 'iso6523' => array( 'label' => __( 'ISO 6523 code', 'ai-rank-suite' ), 'prop' => 'iso6523Code', 'region' => 'eu', 'hint' => __( 'Used on EU e-invoices (Peppol).', 'ai-rank-suite' ), ), 'naics' => array( 'label' => __( 'NAICS code', 'ai-rank-suite' ), 'prop' => 'naics', 'region' => 'us', 'hint' => __( 'North American industry classification.', 'ai-rank-suite' ), ), 'isic' => array( 'label' => __( 'ISIC v4 code', 'ai-rank-suite' ), 'prop' => 'isicV4', 'region' => 'global', 'hint' => __( 'UN industry classification — the international equivalent of NAICS.', 'ai-rank-suite' ), ), 'gln' => array( 'label' => __( 'GLN (global location number)', 'ai-rank-suite' ), 'prop' => 'globalLocationNumber', 'region' => 'global', 'hint' => __( 'GS1 identifier — retail and logistics partners match on it.', 'ai-rank-suite' ), ), ); } /** * Trust and editorial policies Google reads for E-E-A-T, and news * publishers are required to declare. * * @return array */ public static function policies(): array { return array( 'publishing' => array( 'label' => __( 'Editorial guidelines', 'ai-rank-suite' ), 'prop' => 'publishingPrinciples', 'hint' => __( 'The page explaining how you decide what to publish.', 'ai-rank-suite' ), ), 'ethics' => array( 'label' => __( 'Ethics policy', 'ai-rank-suite' ), 'prop' => 'ethicsPolicy', 'hint' => __( 'Conflicts of interest, gifts, sponsorship.', 'ai-rank-suite' ), ), 'corrections' => array( 'label' => __( 'Corrections policy', 'ai-rank-suite' ), 'prop' => 'correctionsPolicy', 'hint' => __( 'How mistakes are fixed and disclosed. A strong trust signal.', 'ai-rank-suite' ), ), 'ownership' => array( 'label' => __( 'Ownership & funding', 'ai-rank-suite' ), 'prop' => 'ownershipFundingInfo', 'hint' => __( 'Who owns you and who pays for the content.', 'ai-rank-suite' ), ), 'feedback' => array( 'label' => __( 'Feedback policy', 'ai-rank-suite' ), 'prop' => 'actionableFeedbackPolicy', 'hint' => __( 'How readers reach you about the content.', 'ai-rank-suite' ), ), 'diversity' => array( 'label' => __( 'Diversity policy', 'ai-rank-suite' ), 'prop' => 'diversityPolicy', 'hint' => __( 'Required of news publishers in Google News.', 'ai-rank-suite' ), ), 'unnamed' => array( 'label' => __( 'Unnamed-sources policy', 'ai-rank-suite' ), 'prop' => 'unnamedSourcesPolicy', 'hint' => __( 'When anonymous sourcing is allowed.', 'ai-rank-suite' ), ), ); } /** * Contact-point roles. Each can carry its own languages and served areas, * which is what makes an international business resolvable per market. * * @return array */ public static function contact_types(): array { return array( 'customer support' => __( 'Customer support', 'ai-rank-suite' ), 'sales' => __( 'Sales', 'ai-rank-suite' ), 'technical support' => __( 'Technical support', 'ai-rank-suite' ), 'billing support' => __( 'Billing', 'ai-rank-suite' ), 'reservations' => __( 'Reservations', 'ai-rank-suite' ), 'emergency' => __( 'Emergency', 'ai-rank-suite' ), 'press' => __( 'Press', 'ai-rank-suite' ), 'bill payment' => __( 'Payments', 'ai-rank-suite' ), ); } /** * @return array */ public static function defaults(): array { return array( 'logo' => '', // Dedicated Organization logo URL; site icon is only the fallback. 'legal_name' => '', 'alt_name' => '', 'description' => '', 'slogan' => '', 'founded' => '', 'founder' => '', 'employees' => '', 'email' => '', 'phone' => '', 'same_as' => array(), // list 'knows_about' => array(), // list 'area_served' => array(), // list — ISO country codes or region names 'languages' => array(), // list 'currencies' => array(), // list 'payments' => array(), // list 'price_range' => '', 'awards' => array(), // list 'certifications' => array(), // list 'member_of' => array(), // list 'parent_org' => '', 'identifiers' => array(), // key => value from identifiers() 'policies' => array(), // key => URL from policies() 'contacts' => array(), // list<{type, phone, email, languages, areas}> ); } /** * Build the properties to merge into the Organization/LocalBusiness node. * * Returns only what is set: an empty form adds nothing, so switching the * feature on can never make an existing graph worse. * * @param array $s Identity settings. * @return array */ public static function properties( array $s ): array { $s = array_merge( self::defaults(), $s ); $out = array(); $scalars = array( 'legalName' => 'legal_name', 'alternateName' => 'alt_name', 'description' => 'description', 'slogan' => 'slogan', 'foundingDate' => 'founded', 'email' => 'email', 'telephone' => 'phone', 'priceRange' => 'price_range', ); foreach ( $scalars as $prop => $key ) { $value = trim( (string) $s[ $key ] ); if ( '' !== $value ) { $out[ $prop ] = $value; } } if ( '' !== trim( (string) $s['founder'] ) ) { $out['founder'] = array( '@type' => 'Person', 'name' => trim( (string) $s['founder'] ), ); } if ( '' !== trim( (string) $s['employees'] ) ) { $out['numberOfEmployees'] = array( '@type' => 'QuantitativeValue', 'value' => trim( (string) $s['employees'] ), ); } if ( '' !== trim( (string) $s['parent_org'] ) ) { $out['parentOrganization'] = array( '@type' => 'Organization', 'name' => trim( (string) $s['parent_org'] ), ); } $lists = array( 'sameAs' => 'same_as', 'knowsAbout' => 'knows_about', 'areaServed' => 'area_served', 'knowsLanguage' => 'languages', 'currenciesAccepted' => 'currencies', 'award' => 'awards', 'memberOf' => 'member_of', ); foreach ( $lists as $prop => $key ) { $values = array_values( array_filter( array_map( 'trim', (array) $s[ $key ] ) ) ); if ( ! empty( $values ) ) { $out[ $prop ] = 1 === count( $values ) && in_array( $prop, array( 'currenciesAccepted' ), true ) ? $values[0] : $values; } } $payments = array_values( array_filter( array_map( 'trim', (array) $s['payments'] ) ) ); if ( ! empty( $payments ) ) { $out['paymentAccepted'] = implode( ', ', $payments ); } $certs = array_values( array_filter( array_map( 'trim', (array) $s['certifications'] ) ) ); if ( ! empty( $certs ) ) { $out['hasCredential'] = array_map( static fn( string $c ): array => array( '@type' => 'EducationalOccupationalCredential', 'name' => $c, ), $certs ); } // Registration identifiers. Everything except the three schema.org // properties that take a bare string goes into identifier[] as a // PropertyValue, which is how a machine tells an LEI from a DUNS. $defs = self::identifiers(); $property_id = array(); foreach ( (array) $s['identifiers'] as $key => $value ) { $value = trim( (string) $value ); if ( '' === $value || ! isset( $defs[ $key ] ) ) { continue; } $prop = (string) $defs[ $key ]['prop']; if ( 'identifier' === $prop ) { $property_id[] = array( '@type' => 'PropertyValue', 'name' => (string) $defs[ $key ]['label'], 'propertyID' => strtoupper( (string) $key ), 'value' => $value, ); continue; } $out[ $prop ] = $value; } if ( ! empty( $property_id ) ) { $out['identifier'] = $property_id; } $policy_defs = self::policies(); foreach ( (array) $s['policies'] as $key => $url ) { $url = trim( (string) $url ); if ( '' !== $url && isset( $policy_defs[ $key ] ) && wp_http_validate_url( $url ) ) { $out[ (string) $policy_defs[ $key ]['prop'] ] = $url; } } $contacts = array(); foreach ( (array) $s['contacts'] as $contact ) { if ( ! is_array( $contact ) ) { continue; } $phone = trim( (string) ( $contact['phone'] ?? '' ) ); $email = trim( (string) ( $contact['email'] ?? '' ) ); if ( '' === $phone && '' === $email ) { continue; } $node = array_filter( array( '@type' => 'ContactPoint', 'contactType' => trim( (string) ( $contact['type'] ?? 'customer support' ) ), 'telephone' => '' !== $phone ? $phone : null, 'email' => '' !== $email ? $email : null, ) ); $langs = array_values( array_filter( array_map( 'trim', (array) ( $contact['languages'] ?? array() ) ) ) ); if ( ! empty( $langs ) ) { $node['availableLanguage'] = $langs; } $areas = array_values( array_filter( array_map( 'trim', (array) ( $contact['areas'] ?? array() ) ) ) ); if ( ! empty( $areas ) ) { $node['areaServed'] = $areas; } $contacts[] = $node; } if ( ! empty( $contacts ) ) { $out['contactPoint'] = $contacts; } /** * Filter the identity properties before they are merged into the graph. * * @param array $out Properties. * @param array $s Raw settings. */ return (array) apply_filters( 'airanksuite/schema/identity', $out, $s ); } /** * How complete the entity is, as a percentage plus what is missing. * * Scored by GEO value rather than by field count: sameAs and knowsAbout do * more for citation than a slogan ever will. * * @param array $s Identity settings. * @return array{score: int, missing: list} */ public static function completeness( array $s ): array { $s = array_merge( self::defaults(), $s ); $weights = array( array( 'key' => 'same_as', 'label' => __( 'Profiles (sameAs)', 'ai-rank-suite' ), 'why' => __( 'The links that let a knowledge graph merge your site with the company it already knows. Without them you are a new, unverified name.', 'ai-rank-suite' ), 'weight' => 22, 'set' => ! empty( array_filter( (array) $s['same_as'] ) ), ), array( 'key' => 'knows_about', 'label' => __( 'Subjects you know (knowsAbout)', 'ai-rank-suite' ), 'why' => __( 'An explicit list of the topics you claim expertise in — the most direct expertise signal an assistant can read, and almost nobody sets it.', 'ai-rank-suite' ), 'weight' => 18, 'set' => ! empty( array_filter( (array) $s['knows_about'] ) ), ), array( 'key' => 'description', 'label' => __( 'Description', 'ai-rank-suite' ), 'why' => __( 'The sentence an assistant repeats when asked who you are.', 'ai-rank-suite' ), 'weight' => 14, 'set' => '' !== trim( (string) $s['description'] ), ), array( 'key' => 'identifiers', 'label' => __( 'Registration identifiers', 'ai-rank-suite' ), 'why' => __( 'VAT, LEI, DUNS or a register number turn a claimed business into a verifiable one.', 'ai-rank-suite' ), 'weight' => 12, 'set' => ! empty( array_filter( (array) $s['identifiers'] ) ), ), array( 'key' => 'contacts', 'label' => __( 'Contact points', 'ai-rank-suite' ), 'why' => __( 'Per-role, per-language contacts are what make you resolvable in each market you sell to.', 'ai-rank-suite' ), 'weight' => 10, 'set' => ! empty( (array) $s['contacts'] ), ), array( 'key' => 'area_served', 'label' => __( 'Areas served', 'ai-rank-suite' ), 'why' => __( 'Assistants filter by geography before they filter by quality.', 'ai-rank-suite' ), 'weight' => 8, 'set' => ! empty( array_filter( (array) $s['area_served'] ) ), ), array( 'key' => 'founded', 'label' => __( 'Founding date', 'ai-rank-suite' ), 'why' => __( 'Longevity is a trust proxy, and it disambiguates you from same-named companies.', 'ai-rank-suite' ), 'weight' => 6, 'set' => '' !== trim( (string) $s['founded'] ), ), array( 'key' => 'policies', 'label' => __( 'Editorial policies', 'ai-rank-suite' ), 'why' => __( 'Google reads these for E-E-A-T, and news surfaces require them.', 'ai-rank-suite' ), 'weight' => 6, 'set' => ! empty( array_filter( (array) $s['policies'] ) ), ), array( 'key' => 'legal_name', 'label' => __( 'Legal name', 'ai-rank-suite' ), 'why' => __( 'The name on the register, which is how records are matched.', 'ai-rank-suite' ), 'weight' => 4, 'set' => '' !== trim( (string) $s['legal_name'] ), ), ); $score = 0; $missing = array(); foreach ( $weights as $w ) { if ( $w['set'] ) { $score += (int) $w['weight']; } else { $missing[] = array( 'key' => (string) $w['key'], 'label' => (string) $w['label'], 'why' => (string) $w['why'], ); } } return array( 'score' => min( 100, $score ), 'missing' => $missing, ); } }