Find Scholarships by Deadline

Use a Python CLI to build a sourced scholarship shortlist sorted by deadline.

Introduction

30 Second Summary

Scholarship searches often leave you juggling dozens of tabs. Important details can change before you submit an application.

In this project, you will build a sourced scholarship shortlist for your field, study level, and year. A Python command-line tool uses the Desearch API to sort upcoming deadlines before saving your results as Markdown and CSV files.

What You'll Build

Your study details become a deadline-sorted table of scholarships with award amounts, source pages, and the cost of the search.

By the end of this project, you'll have:

A sourced scholarship shortlist showing names, amounts, upcoming deadlines, and a source URL for every result.
Reusable Markdown and CSV results that you can open in results.md or results.csv before checking the top three entries against their official pages.
An offline replay that rebuilds the same shortlist from a saved raw file without an API key or network call.
Secret Mission: An optional challenge to push your scholarship research skills further.

Are there any prerequisites?

You need Python 3.10 or newer plus a Desearch API key from the Desearch console. Attaching a payment card can feel like a big step.

The service provides $5 in credits after you attach it.

Before We Start

A deadline shortlist is only useful when the tool that builds it can run on your computer. This setup removes the avoidable blockers before your first search.

You'll confirm that Python can run the scholarship script. You'll also bring the example files onto your Desktop.

Finally, you'll create a Desearch API key for the searches you run later.

In this step, get ready to:

Confirm that Python 3.10 or newer is available.
Download the scholarship-shortlist files to your Desktop.
Create a Desearch API key for later searches.

Check your Python version

The scholarship finder is a Python script with no extra packages to install. It needs Python 3.10 or newer.

macOS

Press Cmd+Space to open Spotlight Search.
Type Terminal.
Press Enter to open Terminal.
Check your Python version by running this command:

python3 --version

What does this command check?

The --version option asks the Python interpreter to print its version number. The process exits immediately.

Windows

Press the Windows key to open Search.
Type Terminal.
Press Enter to open Terminal.
Check your Python version by running this command:

python --version

What does this command check?

The --version option asks the Python interpreter to print its version number. The process exits immediately.

Match your terminal output to the outcome below.

✔️ I see a supported version

That's one prerequisite handled. Python 3.10 or newer can run the scholarship finder.

ⓧ I see an older version

Your installed version is below the tool's minimum. Install a current Python release before continuing.

macOS

Download a current installer from the official Python downloads for macOS.
Run the downloaded installer.
Close Terminal after the installation finishes.
Reopen Terminal through Spotlight Search.
Verify the updated version by running:

python3 --version

What should you see?

The output should report Python 3.10 or newer. That version can run the scholarship finder.

Windows

Download a current installer from the official Python downloads for Windows.
Run the downloaded installer.
Close Terminal after the installation finishes.
Reopen Terminal through Windows Search.
Verify the updated version by running:

python --version

What should you see?

The output should report Python 3.10 or newer. That version can run the scholarship finder.

Still seeing the older version?

Close every terminal window before checking again. If the old version remains, help me check which Python installation my terminal is using.

ⓧ Command not found

Your terminal cannot currently find Python. Install a current release for your operating system.

macOS

Download a current installer from the official Python downloads for macOS.
Run the downloaded installer.
Close Terminal after the installation finishes.
Reopen Terminal through Spotlight Search.
Verify the installation by running:

python3 --version

What should you see?

The output should report Python 3.10 or newer. Your terminal can now access the interpreter.

Windows

Download a current installer from the official Python downloads for Windows.
Run the downloaded installer.
Close Terminal after the installation finishes.
Reopen Terminal through Windows Search.
Verify the installation by running:

python --version

What should you see?

The output should report Python 3.10 or newer. Your terminal can now access the interpreter.

Python still unavailable?

Restart your computer if the installer completed but the command remains unavailable. If that does not help, help me make Python available from my terminal.

Download the scholarship tool

The example lives in a public GitHub repository. A source archive gives you the script plus its documentation in one download.

Why Download a ZIP?

A ZIP snapshot gives you the files without requiring Git. This keeps the setup focused on running the scholarship finder.

Open the scholarship finder repository in your browser.
Click Code above the file list.
Click Download ZIP.
Double-click the downloaded ZIP file in your Downloads folder.
Open the extracted repository folder.
Find the scholarship-finder folder.
Drag the scholarship-finder folder onto your Desktop.
Open the Desktop copy of scholarship-finder.

Your local folder should show scholarship_finder.py, README.md, sample-output.md, and the tests folder. You now have the complete example ready on your Desktop.

Can't find the scholarship folder?

Check your Downloads folder for the ZIP archive.
Make sure you opened the extracted repository folder.
Search inside that folder for scholarship-finder.

Still stuck? Help me locate the scholarship-finder folder from the downloaded GitHub ZIP.

Create your Desearch API key

Desearch uses your key to authenticate later API calls. The scholarship finder reads that credential when it performs a real search.

The console may ask you to attach a card, which can feel like a big commitment. This step creates the credential only.

Desearch bills by API call. No paid request runs in this setup step.

Open the Desearch Console in your browser.
Select Sign up if you do not have an account.
Sign in to your Desearch account.
Open API Keys.
Click Generate API Key.
Enter scholarship-finder-local as the key name.
Copy the generated key immediately.
Store the copied key in a private password-manager note.

You should now see the generated key listed with its value hidden. Your credential is ready for the tool's first real search.

Keep Your Key Private

Never paste the key into screenshots, public repositories, support messages, or chat. Rotate the key from the Desearch Console immediately if it becomes exposed.

Before the final check, which three signs would prove that your local setup is ready?

Return to the scholarship-finder folder on your Desktop.
Confirm that scholarship_finder.py is visible.
Switch back to the terminal window from earlier.
Confirm that the version output reports Python 3.10 or newer.
Return to the API Keys page in the Desearch Console.
Confirm that your generated key appears with its value hidden.

✔️ Awesome, I've got everything!

Your local environment is ready. You can reach the script, run Python, and retrieve your private Desearch key when the tool needs it.

ⓧ I'd like to double check the full code

The Desktop copy of scholarship-finder contains scholarship_finder.py.

Your terminal reports Python 3.10 or newer.

The Desearch Console lists your generated key with its value hidden.

Project folder prepared with Python available and access to the example scholarship-shortlist tool and a Desearch API key.

Your local project environment is ready. Next, you'll preview the scholarship finder's planned API calls without spending anything.

Test the Search With a Dry Run

A real scholarship search can trigger several paid Desearch API calls before you know what the tool intends to request.

This step gives you a safe preview of those calls. You'll configure your API key first. You'll then inspect the search plan without making an HTTP request.

In this step, get ready to:

Store your Desearch API key in the file the tool checks first.
Run the scholarship finder with its dry-run option.
Confirm the plan reports zero calls and zero cost.

Configure your Desearch API key

The scholarship tool can read your key from ~/.desearch_api_key in your home folder. This file takes priority over the DESEARCH_API_KEY environment variable.

A live API key deserves care, so keep it out of the command you run. The key file should contain only the key itself.

Use a plain-text editor to create ~/.desearch_api_key in your home folder.
Confirm your editor shows the saved path as ~/.desearch_api_key.
Paste only your Desearch API key into the file.
Save ~/.desearch_api_key.
Confirm the saved file contains one line with no label or extra text.

How does the tool load your key?

The tool reads ~/.desearch_api_key before checking DESEARCH_API_KEY. Keeping only the key in that file gives the tool the exact credential value it expects.

A dry run does not load either key source. That separation lets you inspect the request plan without authorizing a call.

Preview the planned API calls

A dry run prints the search calls the tool plans to make. It also shows the maximum number of conditional page extractions.

Before you run this, which call types do you expect the scholarship search plan to include?

Return to the terminal in the local project folder from setup.
Preview the nursing scholarship search plan by running this command:

python3 scholarship_finder.py --field nursing --level undergraduate --year 2027 --dry-run

What does this dry run do?

The --field nursing option builds a nursing scholarship search plan.
The --level undergraduate option narrows that plan to undergraduate study.
The --year 2027 option includes the target year in the planned queries.
The --dry-run option prints the planned calls without sending them.

You'll see one planned POST /search call. You'll also see one planned GET /web call.

The output includes a planned /web/extract stage for up to 3 candidate pages.

At the end, you'll see calls: 0, cost: $0.00000. That summary confirms the dry run made no HTTP calls and cost zero.

Your first run is safely complete because the request plan is visible without touching your API balance.

Can't see the dry-run plan?

Confirm your terminal is in the folder containing scholarship_finder.py.
Check that the command ends with --dry-run.
Check that --field, --level, and --year each have the values shown in the command.

Still stuck? Help me diagnose why the scholarship finder is not showing its dry-run plan.

Your key is configured and the search plan is clear. Next, you'll run a real scholarship search for your own field of study.

Search for Your Scholarships

Your dry run proved the tool can plan a scholarship search without spending anything. A plan still cannot show which deadlines fit your calendar.

A live Desearch API search turns your chosen profile into a shortlist ordered by deadline. The same run records its responses for later replay.

In this step, get ready to:

Choose a search profile for this run.
Run the live scholarship search.
Verify the shortlist plus its raw response log.

Choose your search profile

Your search profile controls which scholarship pages the tool looks for. You need one value for each part of the query.

Record your field of study as your field of study.
Record your education level as your education level.
Record your target scholarship year as your target year.

How does the target year work?

The target year guides the search query. The tool still uses the dates stated by each source page.

Turn your profile into a live query

A live search creates billable API calls. You stay in control because the tool prints the exact call count plus the total cost after the run.

Some source pages can trigger an extraction retry. A quiet terminal for about a minute can still be normal.

Switch back to the terminal in your scholarship project folder.

Before you run the search, where do you expect the closest future deadline to appear in the results?

Run the live search with your recorded profile by using this command:

python3 scholarship_finder.py --field "[[FIELD_OF_STUDY="your field of study"]]" --level "[[EDUCATION_LEVEL="your education level"]]" --year "[[TARGET_YEAR="your target year"]]"

What does this command do?

The --field value focuses the query on your subject area.
The --level value focuses the query on your education stage.
The --year value adds your target year to the query.
The live run searches for scholarship pages through Desearch.
The run saves its recorded responses in the default ./out directory.

Scan the displayed scholarship rows from top to bottom.
Read the usage line at the end of the terminal output.

What should you see?

The first column shows each scholarship name.
The amount column shows the value stated by the source page.
The deadline column starts with the nearest candidate deadline.
The source column gives you a URL for checking the scholarship page.
The final usage line follows the pattern calls: N, cost: $X.XXXXX.

Did the live search stop early?

If you see Authentication failed, return to the API key configuration from earlier. Confirm that it contains your active key.
If every search source fails, confirm that your internet connection can reach Desearch.
If an input is rejected, confirm that your target year contains four digits.

Still stuck? Help me diagnose my scholarship search run.

You have crossed the key threshold. Your shortlist now comes from live search data with a visible cost for the run.

Verify the shortlist and raw log

The raw log preserves the API responses behind your shortlist. It can contain source page content.

Before you inspect the saved evidence, what filename pattern do you expect one completed search to create?

List the saved raw response log by running this command:

ls ./out/raw-*.json

What does this check do?

The shell expands raw-*.json to every matching raw log in ./out. The ls command prints the matching path.

You should see at least one path ending in a timestamped filename like raw-YYYYMMDD-HHMMSS.json.

Compare the first two rows that contain deadlines.
Confirm that the first deadline is no later than the second deadline.
Check that every displayed row has a source URL.
Confirm that the terminal shows the API call count.
Confirm that the terminal shows the run cost.

Cannot find the raw log?

Confirm that the live run reached its final usage line.
Check that you are still inside the scholarship project folder.
Resolve any live-search error before running the search again.

Need a hand? Help me find the raw scholarship response log.

Your live shortlist is ready. Next, you will export it to dedicated Markdown and CSV files for easier review.

Save Your Shortlist

Your live Desearch search already produced a sourced shortlist for your study profile. That result currently lives in terminal output, which is awkward to revisit.

This step saves the shortlist as a Markdown report. It also creates a CSV that you can open as a spreadsheet.

In this step, get ready to:

Write your scholarship shortlist to the results folder.
Open the generated Markdown report.
Inspect the generated CSV.

Write the shortlist to disk

The --out option tells the tool where to place exported files. Using ./results keeps this run's exports in a dedicated folder.

This repeats the live search, so it can add API cost. You stay in control because the tool prints the call count plus the run cost when it finishes.

Switch back to the terminal from your real search.
Press the Up Arrow key until your previous live search command appears.
Move the cursor to the end of the command.
Add --out ./results to the end of the command.

Before you run it, do you expect the saved files to preserve the deadline order you saw in the terminal?

Run the updated command by pressing Enter.

You'll see the shortlist again. The final terminal lines report the API call count plus the run cost.

That's the save complete: your shortlist now has two reusable copies in the results folder.

Do not see the results folder?

Make sure the recalled command is the live search command from earlier. A command containing --dry-run does not write export files.
Check that --out ./results appears once at the end of the command.
Confirm that the live request completed before checking for the folder.

Still stuck? Help me work out why the scholarship tool did not create my results folder.

Open the Markdown report

The Markdown export gives you a readable report that preserves the table structure. It is useful when you want to review the shortlist without changing any rows.

Press Cmd+Space on macOS or the Windows key on Windows to open system search.
Type Finder on macOS or File Explorer on Windows into the search field.
Press Enter to open the file browser.
Return to the local project folder from earlier.
Open the results folder.
Open results.md.

You'll see the saved scholarship table. Each row includes a name, amount, deadline, and source URL.

Does the Markdown file look empty?

Return to the terminal to confirm that the search completed successfully.
Check that you opened results/results.md from the latest run.
Close the file before reopening it if your viewer is showing an older copy.

Need a hand? Help me diagnose why my generated Markdown scholarship report is empty or outdated.

Inspect the CSV export

The CSV arranges each scholarship into spreadsheet cells. This format gives you a practical copy for checking details later.

Before you open it, which deadline do you expect to find in the first scholarship row?

Switch back to the results folder in your file browser.
Open results.csv.

You'll see the nearest upcoming deadline at the top of the scholarship rows. Every row includes a source URL that you can check later.

Your shortlist now lives in readable Markdown plus spreadsheet-ready CSV. Next up, you'll rebuild it from the saved raw data without using your key or making another network call.

Rebuild From the Raw Log

Your generated files already make the shortlist easy to use. The raw JSON log gives you a way to reproduce every row from saved evidence.

In this step, you'll feed that log back into the tool. Replay mode rebuilds the shortlist without loading your API key or contacting the Desearch API.

In this step, get ready to:

Locate the raw response file saved by your real search.
Rebuild the shortlist with replay mode.
Confirm the rebuilt CSV matches the original shortlist.

Locate the saved raw log

The real search stored its responses in a timestamped file beside your exports. Replay mode needs the path to that specific file.

The timestamped name is a bit fiddly to scan. Its raw- prefix is the quickest landmark.

Return to the editor from earlier.
Expand the results folder in the file tree.
Find the file whose name follows raw-YYYYMMDD-HHMMSS.json.
Record its relative path here: results/raw-YYYYMMDD-HHMMSS.json.

You'll see the timestamped raw log in the same folder as results.md and results.csv.

Replay and compare the shortlist

The --from-raw option switches the tool into replay mode. The tool parses saved responses instead of requesting new ones.

Return to the terminal from earlier.

Before you run this, which parts of the previous output do you expect replay mode to preserve?

Rebuild the shortlist from your saved log by running this command:

python3 scholarship_finder.py --from-raw [[RAW_LOG_PATH="results/raw-YYYYMMDD-HHMMSS.json"]] --out ./replayed

What Does Replay Mode Do?

The --from-raw option reads the saved responses from your raw log.
The tool rebuilds the scholarship table from those responses.
The --out ./replayed option saves regenerated copies inside a new replayed folder.
The printed call count and cost describe the saved requests from the original run.
Replay mode makes no new network calls or charges.

You'll see the shortlist appear in the terminal with its names, amounts, deadlines, and source URLs. The tool does not ask for your API key.

Before you compare the files, do you expect any scholarship row to move to a different deadline position?

Return to the editor from earlier.
Open replayed/results.csv from the file tree.
Compare its scholarship rows with the existing results/results.csv file.
Confirm each source URL appears on the same row in both files.

Both CSV files contain the same scholarship rows in the same deadline order. Their matching source URLs show that replay mode rebuilt the same shortlist.

That's a strong reproducibility check. Your shortlist can now be rebuilt from its evidence log without another search.

Raw Log Not Found?

Check that your recorded path starts with the folder containing the original exports.
Confirm the selected raw file came from the search that produced results/results.csv.
Copy the complete timestamped filename into your raw log path variable.

Still stuck? Get help checking which raw log belongs to your original shortlist.

Your shortlist now survives without a live search. Next, you'll check the first three rows against their official source pages.

Verify Your Top Scholarships

Your saved shortlist can now be rebuilt without another API call. Its top deadlines still need to agree with the pages you would rely on before applying.

Award amounts need the same check. A source-backed CSV becomes useful when each important claim survives that comparison.

In this step, you'll inspect the source pages for the first three data rows. You'll record every decision in results/results.csv.

In this step, get ready to:

Add dedicated verification columns to results/results.csv.
Compare the top three deadlines with their official source pages.
Compare the top three award amounts with their official source pages.

Add verification columns

One new column records the outcome of each deadline comparison. A second column records the outcome of each award amount comparison.

Switch back to results/results.csv in the spreadsheet editor from earlier.

You should see the generated scholarship rows below the header row. The first empty header cell is where your verification columns begin.

Enter Deadline match in the first empty header cell.
Enter Amount match in the next empty header cell.

The two new headers should appear beside the generated columns. The original scholarship details should remain unchanged.

Save results/results.csv in your spreadsheet editor.

Good, your CSV now has a clear place for every verification decision.

Did an existing column change?

Undo the edit if either header replaced an existing scholarship field.
Move both verification headers to empty cells after the existing columns.

Still stuck? Help me add verification columns without changing the existing CSV data.

Verify the top three source pages

Source pages can change after a search. Checking each claim against its page shows which rows are ready for closer application planning.

What counts as a match?

A Match means the source page supports the value shown in the CSV. Does not match means the page differs or does not state that value.

A deadline comparison uses the calendar date. An amount comparison includes the currency or stated range.

Begin with the first data row below the header.

Follow the source URL in the first data row to load its official page in your browser.
Find the application deadline on the source page.
Compare the source deadline with the deadline in the first CSV row.
Find the award amount on the source page.
Compare the source amount with the amount in the first CSV row.
Switch back to results/results.csv.
Enter either Match or Does not match in the first row's Deadline match cell.
Enter either Match or Does not match in the first row's Amount match cell.

The first scholarship row should now show one decision for its deadline. It should also show one decision for its amount.

Save results/results.csv.

Source page not opening?

Copy the complete source URL from the same CSV row.
Paste the URL into your browser's address bar.
Load the page by pressing Enter.

Still stuck? Help me open and check a scholarship source URL from my CSV.

The same comparison now applies to the second data row.

Follow the source URL in the second data row to load its official page in your browser.
Find the application deadline on the source page.
Compare the source deadline with the deadline in the second CSV row.
Find the award amount on the source page.
Compare the source amount with the amount in the second CSV row.
Switch back to results/results.csv.
Enter either Match or Does not match in the second row's Deadline match cell.
Enter either Match or Does not match in the second row's Amount match cell.

The second scholarship row should now contain two verification decisions.

Save results/results.csv.

Finish the source review with the third data row.

Follow the source URL in the third data row to load its official page in your browser.
Find the application deadline on the source page.
Compare the source deadline with the deadline in the third CSV row.
Find the award amount on the source page.
Compare the source amount with the amount in the third CSV row.
Switch back to results/results.csv.
Enter either Match or Does not match in the third row's Deadline match cell.
Enter either Match or Does not match in the third row's Amount match cell.

The third scholarship row should now contain two verification decisions.

Save results/results.csv.

Confirm the completed checks

A final pass catches skipped cells or accidental edits before you rely on the shortlist.

Before you check the finished file, how many verification cells do you expect to be filled? Hold that number in mind.

Count the filled cells under Deadline match across the first three data rows.
Count the filled cells under Amount match across the first three data rows.
Confirm that the original deadline entries remain unchanged.
Confirm that the original amount entries remain unchanged.
Confirm that each of the first three rows still contains its source URL.
Save results/results.csv.

You should see six completed verification cells across the top three rows. Every completed cell should contain Match or Does not match.

Each original deadline should still be present. Each original amount and source URL should also remain in place.

Missing a verification mark?

Check that the header row contains two separate verification columns.
Fill any blank verification cell in the first three data rows.
Restore any original scholarship value that was accidentally overwritten.

Still stuck? Help me find the missing verification mark in my scholarship CSV.

That is the trust check complete. Your CSV now shows which top deadlines agree with their sources.

It also shows which award amounts survived the same review.

Secret mission

Build an Application Priority Plan

Turn the three scholarships you already checked into an application priority plan. Audit each opportunity for eligibility plus required materials. Choose your first target using evidence from its official source.

Clean Up Your Resources

Choose whether to keep your local work, pause with the useful files intact, or remove everything. Your local files create no ongoing charges. New Desearch API calls incur usage costs when you run another live search.

Resources you used:

Local project folder containing the example scholarship-shortlist tool.
Checked shortlist in results/results.csv.
Markdown shortlist in results/results.md.
Saved raw API-response log from the real scholarship search.
API key configuration stored in ~/.desearch_api_key or DESEARCH_API_KEY.

Keep everything running

No action is needed. Choose this option if you plan to run more scholarship searches or review your results again.

The raw log can contain source page content. Your API key configuration remains a live credential on your computer.

Keep results/results.csv as your checked shortlist for application planning.
Keep results/results.md as a readable version of the same shortlist.
Keep the saved raw API-response log only if you want to rebuild the shortlist without another network call.
Keep your API key configuration private on your own computer.

Your local files remain available without creating another API charge.

Pause - I'll come back to this later

The scholarship-shortlist tool exits after each command. There is no local server or background process to stop.

Close the terminal used for your completed searches.
Keep the local project folder for your next session.
Keep results/results.csv as your checked shortlist.
Keep results/results.md for a readable view of the results.
Select the saved raw API-response log in your file browser if you do not want to retain source page content.
Move the selected raw log to your operating system's deleted-items area.

Your checked shortlist stays available. No project process remains active.

Delete - I don't want to use this again

Deleting the local project folder removes the scholarship-shortlist tool. It also removes every generated result stored inside that folder.

This cleanup is permanent. Keep a separate copy of your checked CSV if you still need the verified scholarship details.

Keep your checked shortlist first:

Copy results/results.csv to a location outside the local project folder.
Open the copied CSV to confirm that the top three source checks are still present.

Remove the local project files:

Use your file browser to navigate to the location containing the local project folder.
Select the local project folder.
Move the selected folder to your operating system's deleted-items area.
Locate the saved raw API-response log if you stored it outside the local project folder.
Move the separate raw log to your operating system's deleted-items area.

Removing your local key configuration is reversible. You can configure API access again if you return to the tool.

Remove the API key configuration:

Navigate to your home folder if you used the key-file method.
Select ~/.desearch_api_key.
Move the key file to your operating system's deleted-items area.
Return to the shell or system environment settings where you saved the key if you used the environment-variable method.
Remove DESEARCH_API_KEY from those settings.
Empty your operating system's deleted-items area.
Confirm that the local project folder no longer appears in its original location.
Confirm that the saved raw API-response log is gone from any separate storage location.
Confirm that your local API key configuration no longer appears in the storage method you used.

Your local tool files, generated outputs, raw source content, and local key configuration are now removed.

Nice Work!

You made it! You used the Desearch API to build a deadline-sorted scholarship shortlist for your own field. Your checked CSV gives you sourced options that you can review before applying.

You've learned how to:

Used a zero-cost dry run to preview the planned API calls. Ran the real search with your own study criteria. Read the printed call count and cost.
Exported a deadline-sorted shortlist to Markdown and CSV. Kept a source URL on every row.
Rebuilt the same shortlist from raw data without an API key. The rebuild made no network call. Checked the top three scholarships against their official source pages. Recorded the amount and deadline checks in results/results.csv.
Tackled the optional Secret Mission for an extra scholarship-research challenge.

Ready to quiz yourself?