{"name":"MatchAwards public search API","version":"v1","description":"Read-only search over U.S. federal and state contract opportunities, grants, jobs, federal contract awards and grant awards listed on MatchAwards. No key, no cookies. JSON only.","endpoints":{"GET https://matchawards.com/api/public/v1/opportunities":"Search, newest first: { as_of, results: [row], has_more, next_cursor }, and a warning (plain text, with the dates) when the search had to skip a range of posts it could not read in time.","GET https://matchawards.com/api/public/v1/opportunities/{id}":"One notice: { as_of, result: row + description + contacts }.","GET https://matchawards.com/api/public/v1/awards":"Contract and grant awards, newest first: { as_of, results: [award_row], has_more, next_cursor }, and warning as opportunities. Paging as opportunities.","GET https://matchawards.com/api/public/v1/awards/summary":"Who usually wins a NAICS, and for how much: { as_of, result: { window: { from, to, basis: \"posted\", first_award_date, last_award_date }, awards: { count, with_amount, total_amount }, value: { p25, median, p75 } or null, top_awardees: [{ name, uei, duns, awards, total_amount, first_award_date, last_award_date, agencies: [agency_id] }], coverage_note } }.","GET https://matchawards.com/api/public/v1/awards/{id}":"One award: { as_of, result: award_row }.","GET https://matchawards.com/api/public/v1/companies/{uei}":"One awardee by UEI: { as_of, result: { uei, uei_matched_by_name, name, other_names, duns, location, totals, first_award_date, last_award_date, top_naics, top_agencies, recent_awards: [award_row], coverage_note } }; 404 when MatchAwards holds no award for it.","GET https://matchawards.com/api/public/v1/naics":"NAICS codes by words or code prefix: { as_of, results: [{ code, title, opportunities_url }] }.","GET https://matchawards.com/api/public/v1/agencies":"Agencies by name: { as_of, results: [{ agency_id, name, url }] }; agency_id is what rows carry and what /awards?agency= and /opportunities?agency= take.","GET https://matchawards.com/api/public/v1":"This description."},"parameters":{"type":"contract, federal, state, grant, job (default contract: federal notices plus state procurement).","naics":"Comma list of up to 10 six-digit NAICS codes. Unknown codes are ignored; none known gives an empty result. Works for grants too. A notice matches if any of its NAICS codes does, not only its primary one, AI-suggested ones included (naics_matching); the row's naics field shows the primary code.","state":"Two-letter US state code. Many federal notices carry no state yet, so this misses most of them. Not supported with type=grant (grants carry no state): 400 unsupported_filter.","q":"Keyword(s), 2 to 100 characters, matched case-insensitively and literally in the title.","set_aside":"Set-aside code (e.g. SBA, SDVOSBC); type=contract or federal only.","agency":"Up to 5 agency_ids (a row's, or from /agencies), comma-separated: those agencies' notices only; an unknown one is a 400 naming it.","posted_within_days":"1 to 180 (default 180); jobs 1 to 30 (default 30). Open grants default to all time.","open":"true (default) or false; ignored for jobs.","limit":"1 to 50 (default 20).","cursor":"next_cursor of the previous page. Pass the same parameters with it."},"awards_parameters":{"type":"any, contract_award, grant_award (default any).","naics":"As for opportunities, except that a contract award matches its own NAICS only (the codes AI teaming suggestions added are left out); a grant award also matches its CFDA program's other NAICS (naics_matching).","agency":"Up to 5 agency_ids from rows (the agency's MatchAwards username), comma-separated; an unknown one is a 400 naming it.","state":"Two-letter US state code of the place of performance. Contract awards only (grant awards carry no state): with type=grant_award it is a 400 unsupported_filter, with type=any it leaves the contract awards.","awardee":"Awardee name, 2 to 100 characters, matched case-insensitively and literally. Not indexed: a rare name can give short or empty pages with has_more true; keep following next_cursor.","uei":"The awardee's 12-character UEI, exactly.","q":"As for opportunities: in the title (a grant award's title is the recipient name).","awarded_within_days":"1 to 1095 (default 365), counted from when MatchAwards posted the award, which is close to award_date.","limit":"As for opportunities.","cursor":"As for opportunities."},"awards_summary_parameters":{"naics":"Required. Comma list of up to 10 six-digit NAICS codes, as for /awards: a contract award counts under its own NAICS only (AI-suggested codes left out), once.","agency":"As for /awards: up to 5 agency_ids, comma-separated.","state":"As for /awards: contract awards only.","type":"contract_award (the default) only, for now: grant-award summaries come later (type=grant_award or any is a 400 unsupported_filter).","years":"1 to 5 (default 3).","top":"1 to 25 (default 10): how many top_awardees.","others":"q, awardee, uei, awarded_within_days, limit, cursor (the /awards row filters and paging) are a 400 unsupported_filter."},"awards_summary":{"window":"The last `years` years of when MatchAwards posted the awards (basis \"posted\"), which is close to their award dates; first_award_date and last_award_date are the award dates found, for information.","amounts":"Summed over the amounts that parse as award rows' amount does (a number, $ and commas ignored, or a JSON list's first number), as /companies totals; with_amount counts those. value holds their quartiles (interpolated, as SQL percentile_cont), null under 3.","grouping":"An awardee is its UEI (trimmed and upper-cased, when that is 12 letters and digits), else its normalised name: 1. lower-case; 2. delete every . and '; 3. every other run of characters outside a-z and 0-9 (accented letters too) becomes one space; 4. trim; 5. drop these words from the end, repeatedly, but never the first word: llc, inc, incorporated, corp, corporation, co, company, ltd, limited, lp, llp, pllc, pc, plc. So \"Acme Corp.\", \"ACME, INC.\" and \"Acme Corporation Inc\" are one awardee (\"acme\"), and \"L.L.C.\" alone is \"llc\". The same company with and without a UEI is two awardees. An award with neither a UEI nor a name (blank or N/A) counts in awards and value only. name is the most recent spelling, duns the most recent one given.","rank":"top_awardees by awards, then total_amount. agencies: up to 5 agency_ids, the most frequent first. Cached up to 6 hours; as_of is when it was computed.","timeout":"A summary that takes over 3 seconds is a 503 { error: \"timeout\" }, and the same parameters answer that 503 at once for the next 10 minutes: rather than retrying, narrow it (agency, state) or ask for fewer years."},"naics_matching":{"codes":"A notice has its own (primary) NAICS, the row's naics, and can have more, held as copies. Where they come from depends on the type. Federal notices and contract awards: the own one from SAM, the others named by an AI teaming suggestion (a federal notice whose SAM record had no NAICS carries the AI's first choice as its own code, which nothing records, so it is reported in matched_naics). State notices: every code, the own one too, named by the AI. Grants and grant awards: the CFDA program's NAICS. Jobs: the occupation's NAICS.","matching":"On /opportunities a notice matches through any of its codes, AI ones included. On /awards and /awards/summary a contract award matches its own NAICS only (the AI codes are left out); on /awards a grant award matches all of its CFDA program's NAICS.","matched_naics":"With naics, on /opportunities and /awards rows: the requested codes the notice carries (its own, and its grant or job codes; never a state notice's), sorted six-digit strings; absent when there are none.","ai_matched_naics":"With naics, on /opportunities rows: the requested codes an AI teaming suggestion chose (a federal notice's other codes; every code of a state notice). Sorted six-digit strings; absent when there are none. Every requested code a row matched is in exactly one of matched_naics and ai_matched_naics."},"award_rows":"awardee is { name, uei, duns, uei_source }. uei_source says where a federal award's UEI came from: sam_notice (the SAM award notice), or business_db, entity_api or name_match (matched by the awardee name, so it can be wrong); null for grant awards and for awards imported before it was recorded. amount is in USD or null when the source value does not parse; period ({ start, end }) is for grant awards only. One awardee per solicitation (a multi-award solicitation keeps the first). Coverage of federal awards is incomplete. No contacts. With naics, matched_naics (naics_matching).","companies":"uei is 12 letters and digits (any case). Built from every award MatchAwards holds for the UEI and cached up to 6 hours. totals count every award; amounts add those that parse as award rows' amount does. top_naics counts contract awards (grant awards carry no NAICS of the recipient). recent_awards are the 10 newest; an award without a public MatchAwards page has id and url null. uei_matched_by_name is true when any of its federal awards has a uei_source other than sam_notice (the UEI was matched by name).","agencies_parameters":{"q":"Required. 2 to 100 characters, matched case-insensitively and literally in the agency name or agency_id; exact matches first, then names starting with q.","limit":"1 to 25 (default 10)."},"naics_parameters":{"q":"Words, 2 to 100 characters. Common terms the titles don't use (cybersecurity, janitorial, HVAC, staffing, ...) list their usual codes first; then matches against NAICS titles and keywords (best match first). Send q or code, not both.","code":"2 to 6 digits: the six-digit codes starting with them (5415 gives 541511, 541512, ...).","limit":"1 to 25 (default 10)."},"open_rule":"Open means a deadline that parses and is today or later, US Eastern time. A notice without a deadline is never open. A grant closing more than 5 years out still counts as open and carries no_fixed_deadline: true.","paging":"Results are read newest first, a slice of the time window at a time, and the open rule is applied after the read, so a page can hold fewer than limit rows, even none, with has_more true (a sparse filter such as a rare q can take several pages). Keep following next_cursor until has_more is false. De-duplicate on id: with naics, a notice can rarely appear on two pages.","rows":"id is the notice id (the parent of its per-NAICS copies); url is its MatchAwards page; agency_id is the agency's MatchAwards username. With naics, search rows also have matched_naics and ai_matched_naics (naics_matching). Job rows carry title, agency (the employer), agency_id, state, city, posted_at and url; the other fields are null. Contacts are names and titles only. no_fixed_deadline: true marks a grant whose response_deadline is more than 5 years away (a placeholder date); the field is absent otherwise. Where enabled, the detail also carries ai: { fit, reasoning, subcontracting, large_prime, summary, generated: true }, AI-generated text written when the notice was imported, or null when there is none.","limits":"Per IP (IPv6: per /64): 60 requests a minute and 20 per 5 seconds; over that, 429 { error: \"rate_limited\", retry_after } with a Retry-After header. Responses are cached up to 5 minutes (as_of is when the response was built).","errors":{"400":"{ error: \"invalid_parameter\" or \"unsupported_filter\", parameter, message }","404":"{ error: \"not_found\" }","429":"{ error: \"rate_limited\", retry_after }","503":"{ error: \"grants_unavailable\" }: the open grant list is being rebuilt; { error: \"timeout\" } with Retry-After: a query took too long, retry in a minute (/awards/summary: see awards_summary.timeout).","500":"{ error: \"internal_error\" }"},"examples":["https://matchawards.com/api/public/v1/opportunities?naics=541512,541519\u0026limit=10","https://matchawards.com/api/public/v1/opportunities?type=federal\u0026state=VA\u0026set_aside=SBA","https://matchawards.com/api/public/v1/awards?naics=541512\u0026awarded_within_days=1095","https://matchawards.com/api/public/v1/awards/summary?naics=541512\u0026years=3","https://matchawards.com/api/public/v1/naics?q=cybersecurity"],"contact":"https://matchawards.com/about"}