Reference
Tool listing score fields, one by one
Design your listings table once and the monthly job writes itself. Here is each link-score column a directory can store, and the call that fills it.
SEO Tools AI research team ·
The columns, at a glance
| Column | Filled by | Credits | Refresh |
|---|---|---|---|
| dr | bulk_dr, up to 2,000 domains | 1 | Monthly |
| dr_checked_on | Your own job, the day you fetched | 0 | Every run |
| ref_domains | refdomains, sorted by your choice | 2 | Monthly, top listings only |
| top_anchors | anchors | 2 | Quarterly |
| top_pages | toppages | 2 | Quarterly |
| overview_blob | overview (free, no key) | 0 | On demand |
| rival_overlap | intersect, 2 to 10 domains | 2 | When you add a tool |
The columns that earn their space
Start with two. dr is the sort key, and dr_checked_on is the honesty column.
A score without a date looks like a fact, and a month later it is a rumour. The date stops that, and it also lets your job skip rows it refreshed an hour ago after a crash.
Treat everything else as optional. A comparison site that shows referring domains next to the rating gives readers a second number to cross-check, which is more useful than a prettier badge. Our backlink analysis tool page shows how that looks against other checkers.
Pair the columns with the glossary so readers see the same words you use in the back office, and with the sync recipe when you are ready to fill them.
Columns for the links a directory gives out
Scores describe the tool. A directory also hands out links, and those deserve a column of their own. Catalogues that ask for a link back are common, so the question will reach you sooner than you expect.
Start with a yes-or-no field that records the return link. Before you write it, check the listed site yourself, because a remembered answer is the first thing to go wrong in a list of a few hundred rows.
A reciprocal link column
Add reciprocal_link as a yes-or-no column that says whether the listed tool's site links back to you. Say you maintain 300 tools and 40 of them asked for a link in return. That column tells you which listings rest on a favour, and it does so before a reader asks.
Keep the column out of the score sort. It describes the relationship, not the tool, so mixing it into a ranking would make the order harder to explain later.
A status column for links you publish
Record outbound_status with the HTTP status of each link you publish, plus the date you last checked it. A listing that returns a 404 is a broken promise to the reader, and nobody else will notice it for you.
The check can ride on the same monthly run as the score refresh. You add one column and no new schedule, which is the cheapest maintenance a directory can buy.
Write down the promise you were given
When a catalogue asks for a link in return, note the date, the page and the exact wording of the request in a link_note column. A plain note takes a minute to write and saves an argument six months later.
Do not promise a placement you cannot keep. If the return link is never added, the honest move is to mark the row and leave the score alone.
Keeping paid placement apart
If a listing paid for its slot, store a placement value beside the score and never let the score decide the order alone. A high dr must not be the only reason a paid row sits above a better one.
Show the paid flag next to the score, so anyone who sorts the page sees both. A reader who finds the label is a reader who keeps trusting the rest of the list.
The request parameters you will actually use
These are the parameters from the API, in the order a sync job needs them.
action what to do: domain, overview, bulk_dr, refdomains, anchors ...
q one domain, for single-domain actions
domains comma list, for bulk_dr (GET) or send it as a POST body
key your sk_ key, or use the Authorization: Bearer header
page which page of rows
per rows per page, 10 to 5000, up to 1,000 rows per billed call
sort column to sort by
order asc or descNaming and types that age well
Name columns after what they hold, not after a vendor. dr is fine for ours, but if you later add a second metric, dr_ours and da_moz will save you a migration.
Store the rating as an integer from 0 to 100, the date as an ISO string such as 2026-10-01, and counts as integers. A text column that holds 1.2k is a trap for the first person who sorts it.
Keep a source column too, with a short value like seotoolsai. It costs a few bytes and answers the question every future editor asks.
Every response carries ok. Authenticated ones also carry _credits, with the cost of that call and your remaining balance. Log both. Before you map any other field into a column, make one free domain call and read the JSON yourself.
Set up the table in five steps
Name the columns first
Write the column list before you touch an API key, and name each column for what it holds. Leave vendor names out of the column names, so a later metric does not force a rename.
Make one free call
Run overview for a single domain. It needs no key, so you can read the JSON and check the field names against your table before you spend any credit.
Add the score and its date
Store dr as an integer and dr_checked_on as an ISO date. Those two columns are the minimum for a score a reader can trust.
Test on twenty rows
Send bulk_dr for twenty listings you know. Compare three results by hand against the free domain action, and only then run the full list.
Add detail columns for featured rows
Referring domains and anchors cost 2 credits per call, so fetch them for the listings you show in detail. The 1-credit score can still cover every other row.
Worked example: a hypothetical listing record
This is an invented example, not a real listing. Imagine a directory called ToolShelf with a listing for a fictional product, example-seo.test.
Its record holds dr 41, dr_checked_on 2026-10-01 and ref_domains 1,000. That fits the public formula, since log(1001) divided by log(20,000,000) times 100 rounds to 41.
A month later the job refetches and finds 1,800 referring domains, so the rating becomes 45. Only dr and the date change. The review text, the screenshots and the editor's notes stay exactly as written, because the score never touches them.
Which listings deserve a score, and how deep
Not every listing needs the same depth. A directory with a few hundred tools can score every row, but the detail calls are a separate decision with a separate cost.
Score every row, even the ones you hide from readers. A hidden listing still needs a value when someone filters the back office, and a blank cell there looks like a missing check rather than a choice.
Two listings on one domain
Two listings can share one host, for example a tool and its free trial page on the same site. A score belongs to a domain, so both rows get the same dr.
Add a short text note such as shares domain to the second row. Without it, an editor sees two identical numbers and assumes one of them is a copy error.
The same rule covers a company that runs several tools under one site. Each tool may deserve its own page, but its score is still the score of the domain it lives on, so say that in the note column.
Spend detail calls where readers look
The top of a category is where a referring-domain count changes a decision. Start the 2-credit calls there and leave the long tail on dr alone.
Revisit the split once a year. Listings move up and down the page, and a row that was buried in March may now deserve the detail call.
Keep the raw response once
Keep the raw JSON for each refresh in one text column or in a separate file. When you change what the page shows, you rebuild from that copy and avoid paying for the same rows twice.
It also gives you a record to point at when a rating looks wrong. Compare the stored response with the current one before you change any score by hand.
Record the ok value next to the stored response as well. A row built from a response that was not ok should be flagged for a second run, not trusted as a score.
Run the refresh in a fixed order
A refresh that touches rows in a random order is hard to audit. Process the rows in the order they appear on the page, and write the run's first and last domain into the log.
If the job stops halfway, the log tells you where to resume. Rows that already carry this month's date can be skipped, and nothing is paid for twice.
Field questions
Should I store the raw JSON for each listing?
Yes, once per refresh. Keep it in a single text or JSON column, then derive dr and the other display fields from it. When you change what you show, you can rebuild pages without calling the API again and paying twice.
What happens if a domain is not in the index?
Do not guess a score. Leave the dr cell empty and show no badge for that listing. Our index holds 181,132,097 domains, which is large but not the whole web, and a blank is more honest than a zero.
Do I need all of these fields on the public page?
No. Show the rating and its date, and perhaps referring domains for featured listings. Keep the rest in the back office for sorting, auditing and spotting listings whose numbers jump between months.