There is a version of judge data that helps you prepare for a hearing, and a version that gets you into trouble. The technical distance between them is small, which is exactly why it is worth writing down where the line falls before anyone ships a feature that crosses it.
The helpful version answers a question every advocate has asked: this matter is listed before a particular bench, so what has that bench actually written on my point. The unhelpful version answers a question nobody should be asking a database: what are this judge's odds. The first is preparation. The second is a leaderboard, and a leaderboard about judicial officers built from uneven public data is a professional hazard dressed up as analytics.
This piece is about building the first and refusing the second. It starts with what GET /judges/search actually does, which is narrower than most people assume, moves through the workflow that turns a resolved name into useful research, and ends on the uses to decline and why declining them is a technical judgement as much as an ethical one.
What GET /judges/search Actually Does
The endpoint is deliberately small. A GET to /judges/search with a q parameter performs a case insensitive substring match against a combined list of Supreme Court and High Court judge names. It returns data as a plain array of name strings, capped at 50. An empty q returns a default 50. The meta object carries the query you sent, a responseTime as a string, and totalMatches so you can tell how much the cap is hiding.
That is the whole contract. No judgment counts, no biographies, no tenure dates, no statistics. It is cheap, it is deterministic, it draws no AI credit, and it is built for one job: turning partial keystrokes into a name.
| Property | Behaviour | Why it matters to your client |
|---|---|---|
| Matching | Case insensitive substring, not fuzzy and not phonetic | A user who mistypes a letter gets nothing back. Debounce input, search on a short prefix, and never require the user to have the spelling right before they see suggestions. |
| Response shape | A plain array of name strings | There are no identifiers to key on. The name is the value you carry forward, which is why resolving to a canonical name matters more here than in an API that returns entity ids. |
| Cap | 50 results maximum | A short query returns a truncated set. Encourage more characters rather than paging, because paging a substring match is not a useful interaction. |
| Empty query | Returns a default 50 rather than an error | Useful for showing something on first focus, but do not present those 50 as a meaningful list of any kind. They are a default, not a ranking. |
| meta.totalMatches | The true number of matches before the cap | Use it to tell the user their query is too broad instead of silently showing them a truncated slice. |
| Cost | A deterministic lookup, no model runs | Safe to call on every debounced keystroke within the rate ceiling of ten requests per minute per API key. Debounce for the limit, not for the price. |
The most important sentence in this article
The endpoint searches a curated name list, not the case corpus. A name that is not in the list will not be returned even if it appears on judgments in the corpus, and a name that is in the list is not a promise that matching cases exist. It is a disambiguation aid, not a coverage guarantee. Design your interface so a user who cannot find a name can still proceed by typing one, because the absence of a suggestion is not evidence of absence in the record.
Why Judge Names Are Harder Than They Look
Names in Indian judicial records are not a solved problem, and any feature built on them has to accommodate that rather than assume it away.
- Honorifics travel inconsistently. Justice, Hon'ble Mr Justice, Hon'ble Ms Justice, J., and bare surnames all appear across registries and across eras. The same person is written several ways depending on which registry published the document and when.
- Initials expand and contract. A judge who appears with two initials in one court's records may appear with a full given name in another's, and with neither in a cause list entry.
- Transliteration varies. Indian names admit multiple defensible English spellings, and different registries settled on different ones. A substring match treats each spelling as a distinct string, because to the index it is one.
- Elevation moves a name between courts. A judge appears in one High Court's records for years and then in Supreme Court records afterwards. The person is continuous and the record is not.
- Surnames repeat. Two judges sharing a surname, sitting in different courts or different decades, are two people, and a substring search over surnames alone will happily merge them in a user's mind.
- Older records are thinner. Metadata completeness varies by court and by year. A judgment from an earlier decade may carry no structured judge field at all, only names inside the text.
This is why the resolution step exists and why it should not be skipped. A user who types three characters into a free text filter is guessing at a string. A user who picks from suggestions is choosing a value the system has actually seen written that way, which is a strictly better input even though it is still not a guarantee.
The Real Workflow: Resolve, Filter, Read
The endpoint is one step of three. On its own it does nothing useful. In sequence it is the difference between a search that returns a court's entire output and one that returns what a particular bench has written on your point.
Resolve what the user typed into a canonical name
Call GET /judges/search with the partial input, debounced, and present the returned names as suggestions. The user picks one. You now hold a string that exists in the name list rather than a string somebody typed from memory, which removes an entire class of empty result sets caused by spelling.
Feed that name into the judge filter on search
POST to /search/cases with your query and the resolved name in judgeName. The field has aliases judges and judge, and it accepts a string, a comma separated string or an array, so a bench of two or three names goes in as one filter rather than as three searches you have to merge yourself.
Combine with the filters that make the question precise
Judge alone is rarely the question. Add court, caseType, year or a fromDate and toDate range in strict YYYY-MM-DD form, and sortBy set to date when you want chronology rather than relevance. A judge filter plus a case type plus a date window is how a broad enquiry becomes a specific one.
Open the records and read them
Take the results through GET /cases/:id for the full record and GET /cases/:id/pdf for the document. Nothing in this workflow substitutes for reading the judgment, and a list of hits is a reading list rather than a finding.
Read benchComposition where analysis exists
For cases that carry AI analysis, GET /cases/:id/analysis returns a benchComposition field alongside opinionType, precedentValue, legalPrinciples, doctrinesApplied and the rest. Where it is present it tells you about the bench that decided the matter. Where it is absent, hasAnalysis will tell you so plainly.
Only a subset of the corpus carries analysis
The keyword corpus runs to roughly 310 million cases. The AI analysed and semantically embedded corpus is far smaller, in the low millions. So benchComposition, opinionType and the other analysis fields exist for a slice of what you can search, not for everything you can find. Build the interface to degrade gracefully: show the analysis where it exists, show the record where it does not, and never let the absence of analysis look like the absence of a case.
What This Is Genuinely Good For
Set against the hype, the legitimate uses are modest and genuinely valuable. Each of them is a research task that advocates already perform by hand, badly, because doing it properly by hand is expensive.
Preparing for the bench you are actually appearing before
Your matter is listed. You know the bench. Reading what that bench has written on your point is ordinary preparation, and it has been ordinary preparation for as long as there have been law reports. Resolving the name and filtering a search on it simply makes an hour's work into ten minutes of it. What you take away is reasoning and language, not a probability.
Checking for a coordinate bench taking a different view
A different view taken by a coordinate bench is a fact of professional significance, and finding it is a duty rather than an advantage. Filtering by judge and by court across a date range is a practical way of locating divergence that a subject search alone will miss.
Autocomplete that stops free text in a filter
The least glamorous use and possibly the most valuable. A filter that accepts anything a user types produces silent empty results the user reads as an absence of authority. A filter populated from a name list produces inputs the system can actually match, and tells the user when a name is not there.
Tracing a line of reasoning through a court
When a doctrine develops across a series of judgments, the judges who wrote them are part of how you follow the thread. Using names to assemble that sequence is intellectual history, and it is exactly what a citator or a well built research workflow is for.
Notice the common shape. Every one of these uses treats a name as an index into the reasoning, and ends with a person reading judgments. None of them ends with a number about a judge.
The Uses to Refuse
Now the part that some product roadmaps will not want to hear. There is a category of judge analytics that should not be built on this data, and the reasons are both professional and technical. Take the professional ones first, because they are the ones that end careers, and then the technical ones, because they are the ones that make the whole idea a fabrication.
The professional hazard
Publishing statistics that purport to score judicial officers is not a neutral technical act. It touches on the dignity of the court and on how the administration of justice is publicly represented, and it invites a reputational exposure for whoever publishes it that no analytics feature is worth. Advocates carry professional obligations to the court that do not evaporate because a number was produced by software rather than said aloud. A firm that ships a judge leaderboard has created a permanent, attributable artefact making claims about named judicial officers, and it will be read by people who did not build it and do not know its limits.
There is a second order harm that is easier to overlook. A prediction shown to a litigant changes their decisions. Someone may settle a strong matter because a screen told them their odds were poor before a named judge. The number was never reliable, the litigant never had the means to evaluate it, and the consequence lands entirely on them.
The technical objection, which is independent of the ethics
Even if none of the above troubled you, the numbers would be wrong, and it is worth being specific about why rather than gesturing at data quality.
- The denominator does not exist. A win rate requires knowing every matter a judge decided and how each ended. Coverage and metadata completeness vary by court and by year, District Court records are thinner than Supreme Court records, and older records are thinner than recent ones. You would be computing a rate over an unknown and non-random sample.
- Outcome is not a field with a clean binary value. Disposal nature covers allowed, dismissed, disposed of, withdrawn, settled, abated, remanded and more, and which of those counts as a win depends entirely on which party you act for and what relief was actually sought. A judgment that grants part of the relief is not a row in a two column table.
- Benches are collective and rotate. Most appellate matters are decided by a bench rather than by an individual, rosters change, and attributing an outcome to one name misrepresents how the decision was made. benchComposition describes who sat, not who decided what.
- Case allocation is not random. Judges hear the matters their roster assigns them. A judge sitting in a criminal roster and one sitting in a commercial roster face entirely different mixes, and comparing their outcome rates compares the dockets rather than the judges.
- Names do not resolve cleanly. Everything in the name problem above applies here with compound force. Merge two judges sharing a surname and your statistic is about a person who does not exist.
- Selection effects run through the whole record. Matters that settle never reach judgment. Matters that go up on appeal are systematically unlike those that do not. Anything computed on decided cases is computed on a filtered population, and the filter correlates with the very thing being measured.
A judge statistic built on Indian court data would be improper if it were accurate, and it is not accurate. Those are two independent reasons to decline, and either one is sufficient.
The precision illusion
The specific danger of this category is that the output looks rigorous. A percentage rendered to one decimal place carries an authority that its inputs cannot support, and users do not read the methodology note. If you build it, it will be quoted back to you without the caveats, in contexts you did not anticipate, by people advising clients. A number that cannot be defended in the room where it will be used should not be produced in the first place.
Designing the Feature So It Stays on the Right Side
The distinction is not merely a policy you write down. It can be built into the interface, and building it in is more durable than documenting it.
- Make judgments the destination. Every path through a judge feature should end at a document a person reads. If any path ends at a number about a judge, that path is the problem.
- Present names as filters, never as subjects. A judge name is a way of narrowing a corpus. It is not an entity with a profile page carrying statistics, and giving it one changes what the feature is regardless of what the statistics say.
- Do not aggregate outcomes by judge, at all. Not as a chart, not as a count, not as a helpful summary line. The aggregation is the feature you are declining to build, and it does not become acceptable at a smaller font.
- Show coverage limits in the interface. State that the name list is curated, that only a subset of the corpus carries analysis, and that what you display is a view of what registries published. A user who knows the limits uses the tool correctly.
- Let a user proceed without a suggestion. If a name is not in the list, allow the free text and say plainly that no suggestion matched. Blocking the search implies the judge does not exist, which is a stronger claim than the data supports.
- Handle the empty result honestly. No results for a judge filter means no matching records were found in what is indexed. It does not mean the judge decided nothing on the point, and your empty state should say the first thing rather than imply the second.
Putting It Together
The complete feature is short. Debounce the input and call GET /judges/search with q, showing the returned names as suggestions and using meta.totalMatches to tell the user when their query is too broad for the cap of 50. When the user picks a name, put it into judgeName on a POST to /search/cases, alongside court, caseType and a date window, with sortBy set to date when chronology is what the user wants. Render the results as a reading list. Open each through GET /cases/:id, and where GET /cases/:id/analysis reports hasAnalysis, surface benchComposition and the rest of the analysis alongside the document rather than instead of it.
What the user ends up with is the set of judgments a particular bench has written that touch their point, in date order, ready to read. That is a real research capability and it did not require a single statistic about a judge to deliver. The full field list for the analysis payload, the exact filter semantics on the search endpoint and the shape of the judge search response are all in the endpoint reference, and there is an API overview.
The argument, in one line, is this. Judge data earns its place in preparation workflows, where it points a lawyer at reasoning they then read and weigh for themselves. It has no place in prediction, where it produces numbers that are improper to publish and, on this corpus, would be wrong even if they were not.
Use judge data to prepare, not to predict
GET /judges/search does one narrow thing well: a case insensitive substring match over a curated Supreme Court and High Court name list, returning up to 50 names with totalMatches in meta, cheaply and without drawing AI credit. Its value is in resolving what a user typed into a name the corpus will match, which then feeds the judgeName filter on POST /search/cases and, where analysis exists, the benchComposition field on the analysis payload. That chain answers a genuine question about what a bench has written on your point. It does not answer, and should not be made to answer, how a judge will rule. Endpoint by endpoint detail is at the API documentation, plan and credit terms are at API pricing, and there is an API overview.
Explore CourtMesh
