My Board Looked Full but the Jobs Were Empty

The board looked healthy from the archive page and hollow one click deeper, every job’s body was a summary paragraph and nothing else. The cause was one API parameter, my search requests asked USAJOBS for minimal fields, and the fix, plus the tool that repaired a thousand existing stubs, taught me how much of an aggregator’s quality is decided by exactly what you ask the source for. This post is the Fields upgrade.

USAJOBS’s search accepts a Fields parameter, and the difference between its values is the difference between a stub and a job announcement:

// before: fast, and hollow
$url = 'https://data.usajobs.gov/api/search?Keyword=army&Fields=Min';

// after: the complete announcement per position
$url = 'https://data.usajobs.gov/api/search?Keyword=army&Fields=Full';

Fields=Full returns what a job seeker actually needs, and the importer maps each section into the post body with proper headings, Summary, Duties, Qualifications, Requirements, Education, Evaluations, Benefits, Required Documents, pulled from the MatchedObjectDescriptor’s UserArea details:

$d = $item['MatchedObjectDescriptor'];
$sections = array(
    'Duties'             => $d['UserArea']['Details']['MajorDuties'],
    'Qualifications'     => $d['QualificationSummary'],
    'Requirements'       => $d['UserArea']['Details']['Requirements'],
    'Education'          => $d['UserArea']['Details']['Education'],
    'Benefits'           => $d['UserArea']['Details']['Benefits'],
    'Required Documents' => $d['UserArea']['Details']['RequiredDocuments'],
);
$body = '';
foreach ($sections as $h => $content) {
    if (empty($content)) { continue; }   // never render empty headings
    $body .= '<h2>' . esc_html($h) . '</h2>' . jab_clean_html($content);
}

Two disciplines in the mapping. Sections render only when the source provides them, an Education heading over nothing is worse than no heading. And everything passes a cleaner, jab_clean_html, because source content arrives with inconsistent markup, stray break tags, wall-of-text paragraphs, and the formatting pipeline that grew around this deserves and gets its own ongoing attention, the short version is that imported HTML is raw material, not finished product.

Then the existing problem, a thousand jobs already imported as stubs. Deleting and refetching would have destroyed edits and history, so the plugin grew a Rebuild Descriptions tool, it walks existing jobs, refetches each position’s full data, and rebuilds only bodies that are short or summary-only by default, leaving already-complete posts untouched. That default is the tool’s wisdom, repair jobs target the broken subset, and a rebuild that rewrites everything indiscriminately is just data loss with a progress bar.

A few things people ask me about this

Why are my imported jobs just summaries? Your search request is asking for minimal fields. Check the API’s field options, on USAJOBS, Fields=Full returns the complete announcement sections.

How do I fix records imported before a mapping fix? A repair tool that refetches by the source’s stable id and rebuilds only records failing a deficiency test, short bodies, missing sections, so good records and manual edits survive.

Next

Full announcements created the project’s hardest honest problem, my pages now contained the same text as the official source and every other aggregator. The duplicate-content fight is the next post.