postalref is an MCP server published by com.postalref, hosted at postalref.com. When last checked on 2026-11-22 it was working: it answers and lists its tools. It declares 6 tools, including decode, lookup, diff, search, read.
USPS package barcodes, service type codes and mailing terms, each cited to its USPS source.
Nothing else in the archive shares these values.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
Read a package barcode or tracking number (IMpb), or a letter's or flat's Intelligent Mail barcode (IMb) from its digits or bars: its layout, each field's digits and meaning, whether the check digit or the bars' frame check holds, and the service type code's or Service Type ID's row in the USPS list, each with the passage that says so. A field's `meaning` is postalref's words: quote a cite's `lit`, USPS's, with its passage.
| Parameter | Type | Description |
|---|---|---|
| barcode * | string | The digits under a package barcode, or all 30 or 34 with 420 and the ZIP Code. Or a letter's or flat's Intelligent Mail barcode: its 20, 25, 29 or 31 digits, or its 65 bars as A, D, F and T from the left. Spaces and dashes are fine. |
{
"name": "decode",
"title": "Decode a barcode",
"description": "Read a package barcode or tracking number (IMpb), or a letter's or flat's Intelligent Mail barcode (IMb) from its digits or bars: its layout, each field's digits and meaning, whether the check digit or the bars' frame check holds, and the service type code's or Service Type ID's row in the USPS list, each with the passage that says so. A field's `meaning` is postalref's words: quote a cite's `lit`, USPS's, with its passage.",
"inputSchema": {
"type": "object",
"required": [
"barcode"
],
"properties": {
"barcode": {
"type": "string",
"maxLength": 160,
"description": "The digits under a package barcode, or all 30 or 34 with 420 and the ZIP Code. Or a letter's or flat's Intelligent Mail barcode: its 20, 25, 29 or 31 digits, or its 65 bars as A, D, F and T from the left. Spaces and dashes are fine."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"digits",
"tracking",
"spec",
"format",
"fields",
"checks",
"verdict"
],
"properties": {
"spec": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"additionalProperties": true
},
"checks": {
"type": "array",
"items": {
"type": "object",
"required": [
"rule",
"outcome",
"text",
"cites"
],
"properties": {
"rule": {
"type": "string"
},
"text": {
"type": "string"
},
"cites": {
"type": "array",
"items": {
"type": "object",
"required": [
"passage",
"lit"
],
"properties": {
"at": {
"type": "string"
},
"lit": {
"type": "array",
"items": {
"type": "string"
}
},
"field": {
"type": "string"
},
"passage": {
"type": "string"
}
},
"additionalProperties": true
}
},
"outcome": {
"enum": [
"pass",
"fail",
"warn"
],
"type": "string"
}
},
"additionalProperties": true
}
},
"digits": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"label",
"name",
"digits",
"meaning",
"cites",
"length"
],
"properties": {
"key": {
"type": "string"
},
"code": {
"type": "object",
"required": [
"table",
"code",
"listed",
"rows"
],
"properties": {
"code": {
"type": "string"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"required": [
"passage",
"revision",
"place",
"cells",
"checked",
"references"
],
"properties": {
"cells": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value"
],
"properties": {
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"notes": {
"type": "array",
"items": {
"type": "object",
"required": [
"mark",
"text",
"revision",
"page"
],
"properties": {
"mark": {
"type": "string",
"minLength": 1
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"text": {
"type": "string",
"minLength": 1
},
"revision": {
"type": "string"
}
},
"additionalProperties": true
}
},
"place": {
"anyOf": [
{
"type": "object",
"required": [
"_tag",
"page"
],
"properties": {
"_tag": {
"enum": [
"Text"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
},
"section": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"page",
"table"
],
"properties": {
"_tag": {
"enum": [
"TableRow"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"sheet",
"row"
],
"properties": {
"row": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"_tag": {
"enum": [
"SheetRow"
],
"type": "string"
},
"sheet": {
"type": "string"
}
},
"additionalProperties": true
}
]
},
"filled": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value",
"from"
],
"properties": {
"from": {
"type": "string"
},
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"checked": {
"type": "boolean"
},
"passage": {
"type": "string"
},
"revision": {
"type": "string"
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"table",
"code"
],
"properties": {
"row": {
"type": "object",
"required": [
"passage",
"cells",
"checked"
],
"properties": {
"cells": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value"
],
"properties": {
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"checked": {
"type": "boolean"
},
"passage": {
"type": "string"
}
},
"additionalProperties": true
},
"code": {
"type": "string"
},
"table": {
"type": "string"
},
"column": {
"type": "string"
},
"removed": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"table": {
"type": "object",
"required": [
"slug",
"name",
"document",
"edition"
],
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"edition": {
"type": "string"
},
"document": {
"type": "string"
}
},
"additionalProperties": true
},
"listed": {
"type": "boolean"
},
"removed": {
"type": "string"
}
},
"additionalProperties": true
},
"name": {
"type": "string"
},
"cites": {
"type": "array",
"items": {
"type": "object",
"required": [
"passage",
"lit"
],
"properties": {
"at": {
"type": "string"
},
"lit": {
"type": "array",
"items": {
"type": "string"
}
},
"field": {
"type": "string"
},
"passage": {
"type": "string"
}
},
"additionalProperties": true
}
},
"label": {
"type": "string"
},
"digits": {
"type": "string"
},
"length": {
"type": "object",
"required": [
"passage",
"lit"
],
"properties": {
"at": {
"type": "string"
},
"lit": {
"type": "array",
"items": {
"type": "string"
}
},
"field": {
"type": "string"
},
"passage": {
"type": "string"
}
},
"additionalProperties": true
},
"meaning": {
"type": "string"
}
},
"additionalProperties": true
}
},
"format": {
"type": "object",
"required": [
"id",
"name",
"length",
"cites"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"cites": {
"type": "array",
"items": {
"type": "object",
"required": [
"passage",
"lit"
],
"properties": {
"at": {
"type": "string"
},
"lit": {
"type": "array",
"items": {
"type": "string"
}
},
"field": {
"type": "string"
},
"passage": {
"type": "string"
}
},
"additionalProperties": true
}
},
"length": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": true
},
"verdict": {
"enum": [
"valid",
"invalid",
"unknown-code"
],
"type": "string"
},
"tracking": {
"type": "string"
}
},
"additionalProperties": true
},
"annotations": {
"title": "Decode a barcode",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}None yet. Changes appear after a server's second daily check.
Look up a USPS code: its row as USPS prints it in the newest edition that lists it, the codes its cells name, the editions that list it and its history, each row with its passage id. A code is found without the marks USPS prints around it and in a row USPS prints for several codes: 750 finds *750, 858 finds 858 and the dropped 858**, and 13 finds PTR's row 01 / 13. Two digits are also tried as three: 55 finds PTR's 55, then STC's 055. Cite a row by its passage, revision and page, with its cells' words as printed, and a row's `notes`, the footnotes its marks point to, by their own revision and page.
| Parameter | Type | Description |
|---|---|---|
| code * | string | A code as USPS prints it: 055, 920, PM, 01. |
| table | string | One table to look in: stc, extra-services, mail-classes, channel-application-ids, container-types, delivery-option-indicators, rate-indicators, destination-rate-indicators, discount-types, open-and-distribute-content-indicators, postal-routing-barcodes, processing-categories, surcharge-types, zones,… |
{
"name": "lookup",
"title": "Look up a code",
"description": "Look up a USPS code: its row as USPS prints it in the newest edition that lists it, the codes its cells name, the editions that list it and its history, each row with its passage id. A code is found without the marks USPS prints around it and in a row USPS prints for several codes: 750 finds *750, 858 finds 858 and the dropped 858**, and 13 finds PTR's row 01 / 13. Two digits are also tried as three: 55 finds PTR's 55, then STC's 055. Cite a row by its passage, revision and page, with its cells' words as printed, and a row's `notes`, the footnotes its marks point to, by their own revision and page.",
"inputSchema": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"maxLength": 40,
"description": "A code as USPS prints it: 055, 920, PM, 01."
},
"table": {
"type": "string",
"description": "One table to look in: stc, extra-services, mail-classes, channel-application-ids, container-types, delivery-option-indicators, rate-indicators, destination-rate-indicators, discount-types, open-and-distribute-content-indicators, postal-routing-barcodes, processing-categories, surcharge-types, zones, impb-noncompliance-codes, impb-noncompliance-report-codes, acs-product-codes, acs-move-types, acs-coa-deliverability-codes, acs-nixie-codes, acs-address-types, acs-fee-notification-codes, acs-notification-types, acs-mail-action-codes, acs-dpv-codes, dpv-return-codes, dpv-footnotes, ptr, ptr2, stid, opcodes, unexpected-opcodes, ncoalink-return-codes, ncoalink-return-code-matrix, lacslink-return-codes, maildat-pre-validation-errors, maildat-client-errors, maildat-client-warnings, maildat-server-errors, maildat-server-warnings, maildat-client-info, impb-quality-validations, impb-cew-messages, impb-international-scan-events, impb-edi-event-codes, impb-barcode-constructs, impb-pc-postage-barcode-constructs, impb-container-barcode-constructs, impb-tray-sack-barcode-constructs, mqd-container-errors, mqd-handling-unit-errors, mqd-bundle-errors, mqd-piece-range-errors or mqd-piece-errors. Every table when absent."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"matches"
],
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"table",
"code",
"listed",
"rows",
"editions",
"history"
],
"properties": {
"code": {
"type": "string"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"required": [
"passage",
"revision",
"place",
"cells",
"checked",
"references"
],
"properties": {
"cells": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value"
],
"properties": {
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"notes": {
"type": "array",
"items": {
"type": "object",
"required": [
"mark",
"text",
"revision",
"page"
],
"properties": {
"mark": {
"type": "string",
"minLength": 1
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"text": {
"type": "string",
"minLength": 1
},
"revision": {
"type": "string"
}
},
"additionalProperties": true
}
},
"place": {
"anyOf": [
{
"type": "object",
"required": [
"_tag",
"page"
],
"properties": {
"_tag": {
"enum": [
"Text"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
},
"section": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"page",
"table"
],
"properties": {
"_tag": {
"enum": [
"TableRow"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"sheet",
"row"
],
"properties": {
"row": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"_tag": {
"enum": [
"SheetRow"
],
"type": "string"
},
"sheet": {
"type": "string"
}
},
"additionalProperties": true
}
]
},
"filled": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value",
"from"
],
"properties": {
"from": {
"type": "string"
},
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"checked": {
"type": "boolean"
},
"passage": {
"type": "string"
},
"revision": {
"type": "string"
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"table",
"code"
],
"properties": {
"row": {
"type": "object",
"required": [
"passage",
"cells",
"checked"
],
"properties": {
"cells": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value"
],
"properties": {
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"checked": {
"type": "boolean"
},
"passage": {
"type": "string"
}
},
"additionalProperties": true
},
"code": {
"type": "string"
},
"table": {
"type": "string"
},
"column": {
"type": "string"
},
"removed": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"table": {
"type": "object",
"required": [
"slug",
"name",
"document",
"edition"
],
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"edition": {
"type": "string"
},
"document": {
"type": "string"
}
},
"additionalProperties": true
},
"listed": {
"type": "boolean"
},
"history": {
"type": "object",
"required": [
"series",
"code",
"first",
"events"
],
"properties": {
"code": {
"type": "string"
},
"first": {
"type": "object",
"required": [
"date",
"fid",
"how",
"rows"
],
"properties": {
"fid": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"how": {
"enum": [
"listed",
"added"
],
"type": "string"
},
"date": {
"type": "string"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"additionalProperties": true
},
"events": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"fid",
"change"
],
"properties": {
"fid": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"row": {
"type": "string"
},
"date": {
"type": "string"
},
"diff": {
"type": "string"
},
"cells": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"marks": {
"type": "string"
},
"change": {
"enum": [
"added",
"removed",
"changed",
"retired",
"unchecked",
"disagreement"
],
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"before",
"after"
],
"properties": {
"after": {
"type": "string"
},
"before": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"series": {
"type": "string"
}
},
"additionalProperties": true
},
"removed": {
"type": "string"
},
"editions": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"revision",
"place",
"checked"
],
"properties": {
"date": {
"type": "string"
},
"place": {
"anyOf": [
{
"type": "object",
"required": [
"_tag",
"page"
],
"properties": {
"_tag": {
"enum": [
"Text"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
},
"section": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"page",
"table"
],
"properties": {
"_tag": {
"enum": [
"TableRow"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"sheet",
"row"
],
"properties": {
"row": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"_tag": {
"enum": [
"SheetRow"
],
"type": "string"
},
"sheet": {
"type": "string"
}
},
"additionalProperties": true
}
]
},
"checked": {
"type": "boolean"
},
"revision": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
},
"annotations": {
"title": "Look up a code",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}What changed in a code table or document between two editions: each code added, removed or changed and each changed section, rated editorial, additive or breaking, with who rated it.
| Parameter | Type | Description |
|---|---|---|
| to | string | The newer edition's date. The newest when absent. |
| code | string | One code of the table. |
| from | string | The older edition's date. The edition before `to` when absent. |
| limit | integer | At most this many changes; 50 when absent. |
| subject * | string | A code table, such as stc, ptr or extra-services, or a document, such as pub-199 or impb-spec. |
| severity | string | Only changes rated this. |
{
"name": "diff",
"title": "Compare two editions",
"description": "What changed in a code table or document between two editions: each code added, removed or changed and each changed section, rated editorial, additive or breaking, with who rated it.",
"inputSchema": {
"type": "object",
"required": [
"subject"
],
"properties": {
"to": {
"type": "string",
"description": "The newer edition's date. The newest when absent."
},
"code": {
"type": "string",
"maxLength": 40,
"description": "One code of the table."
},
"from": {
"type": "string",
"description": "The older edition's date. The edition before `to` when absent."
},
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "At most this many changes; 50 when absent."
},
"subject": {
"type": "string",
"description": "A code table, such as stc, ptr or extra-services, or a document, such as pub-199 or impb-spec."
},
"severity": {
"enum": [
"editorial",
"additive",
"breaking"
],
"type": "string",
"description": "Only changes rated this."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"subject",
"editions",
"to",
"counts",
"total",
"changes"
],
"properties": {
"to": {
"type": "string"
},
"from": {
"type": "string"
},
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"counts": {
"type": "object",
"required": [
"breaking",
"additive",
"editorial",
"pending"
],
"properties": {
"pending": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"additive": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"breaking": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"editorial": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": true
},
"changes": {
"type": "array",
"items": {
"type": "object",
"required": [
"release",
"key",
"subject",
"change",
"ratedBy"
],
"properties": {
"key": {
"type": "string"
},
"row": {
"type": "string"
},
"added": {
"type": "array",
"items": {
"type": "string"
}
},
"pages": {
"type": "object",
"required": [
"before",
"after"
],
"properties": {
"after": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"before": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
}
},
"additionalProperties": true
},
"rated": {
"type": "object",
"required": [
"severity",
"rating",
"model"
],
"properties": {
"model": {
"type": "string"
},
"rating": {
"type": "number"
},
"severity": {
"enum": [
"editorial",
"additive",
"breaking"
],
"type": "string"
}
},
"additionalProperties": true
},
"change": {
"enum": [
"added",
"removed",
"retired",
"changed"
],
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"before",
"after"
],
"properties": {
"after": {
"type": "string"
},
"before": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"carried": {
"type": "object",
"required": [
"from",
"by"
],
"properties": {
"by": {
"type": "string"
},
"on": {
"type": "string"
},
"from": {
"type": "string"
}
},
"additionalProperties": true
},
"ratedBy": {
"enum": [
"rule",
"person",
"model",
"pending"
],
"type": "string"
},
"release": {
"type": "string"
},
"removed": {
"type": "array",
"items": {
"type": "string"
}
},
"subject": {
"anyOf": [
{
"type": "object",
"required": [
"_tag",
"table",
"code"
],
"properties": {
"_tag": {
"enum": [
"Code"
],
"type": "string"
},
"code": {
"type": "string"
},
"table": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"document",
"section"
],
"properties": {
"_tag": {
"enum": [
"Section"
],
"type": "string"
},
"section": {
"type": "string"
},
"document": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"document"
],
"properties": {
"_tag": {
"enum": [
"Document"
],
"type": "string"
},
"document": {
"type": "string"
}
},
"additionalProperties": true
}
]
},
"revision": {
"type": "string"
},
"severity": {
"enum": [
"editorial",
"additive",
"breaking"
],
"type": "string"
},
"rewritten": {
"type": "object",
"required": [
"removed",
"added"
],
"properties": {
"added": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"removed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"subject": {
"type": "object",
"required": [
"slug",
"name",
"kind"
],
"properties": {
"kind": {
"enum": [
"table",
"document"
],
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"additionalProperties": true
},
"editions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
},
"annotations": {
"title": "Compare two editions",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Search the codes, terms, banner texts, specs and documents postalref models, by one index: names and codes whose key is the query's first, then those that start with it, then those with words that start with its words, then codes whose row has its words. A term hit carries its kind (mail-class, extra-service, service, program, system, file, identifier, document, facility, container, role or term) and its tier (core, or reference: only in Publication 32, the glossary of July 2013, with that date). A query of 20 or more digits, or an Intelligent Mail barcode's 65 bars as A, D, F and T, comes back as one to decode. A hit's `path` goes to read: a term's entries, a code's row and history. A code also goes to lookup with its table.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | At most this many hits; 10 when absent. |
| query * | string | A code, a term or words from a code's row: 055, mailer id, ground advantage. |
{
"name": "search",
"title": "Search codes and terms",
"description": "Search the codes, terms, banner texts, specs and documents postalref models, by one index: names and codes whose key is the query's first, then those that start with it, then those with words that start with its words, then codes whose row has its words. A term hit carries its kind (mail-class, extra-service, service, program, system, file, identifier, document, facility, container, role or term) and its tier (core, or reference: only in Publication 32, the glossary of July 2013, with that date). A query of 20 or more digits, or an Intelligent Mail barcode's 65 bars as A, D, F and T, comes back as one to decode. A hit's `path` goes to read: a term's entries, a code's row and history. A code also goes to lookup with its table.",
"inputSchema": {
"type": "object",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "At most this many hits; 10 when absent."
},
"query": {
"type": "string",
"maxLength": 120,
"description": "A code, a term or words from a code's row: 055, mailer id, ground advantage."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"query",
"total",
"hits"
],
"properties": {
"hits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"entity"
],
"properties": {
"see": {
"type": "string"
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"detail": {
"type": "string"
},
"entity": {
"anyOf": [
{
"type": "object",
"required": [
"_tag",
"slug",
"kind",
"tier"
],
"properties": {
"is": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"_tag",
"node"
],
"properties": {
"_tag": {
"enum": [
"Product"
],
"type": "string"
},
"node": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"node"
],
"properties": {
"_tag": {
"enum": [
"Document"
],
"type": "string"
},
"node": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"spec"
],
"properties": {
"_tag": {
"enum": [
"Spec"
],
"type": "string"
},
"spec": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"spec",
"key"
],
"properties": {
"key": {
"type": "string"
},
"_tag": {
"enum": [
"Field"
],
"type": "string"
},
"spec": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"table"
],
"properties": {
"_tag": {
"enum": [
"Table"
],
"type": "string"
},
"table": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"table",
"code"
],
"properties": {
"_tag": {
"enum": [
"Code"
],
"type": "string"
},
"code": {
"type": "string"
},
"table": {
"type": "string"
}
},
"additionalProperties": true
}
]
}
},
"_tag": {
"enum": [
"Term"
],
"type": "string"
},
"kind": {
"enum": [
"mail-class",
"extra-service",
"service",
"program",
"system",
"file",
"identifier",
"document",
"facility",
"container",
"role",
"term"
],
"type": "string"
},
"slug": {
"type": "string"
},
"tier": {
"enum": [
"core",
"reference"
],
"type": "string"
},
"dated": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"table",
"code"
],
"properties": {
"_tag": {
"enum": [
"Code"
],
"type": "string"
},
"code": {
"type": "string"
},
"table": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"table",
"column",
"value"
],
"properties": {
"_tag": {
"enum": [
"Value"
],
"type": "string"
},
"table": {
"type": "string"
},
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
]
}
},
"additionalProperties": true
}
},
"query": {
"type": "string"
},
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"decode": {
"type": "string"
}
},
"additionalProperties": true
},
"annotations": {
"title": "Search codes and terms",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Read a page of postalref.com by its path. /glossary/<id> gives what USPS means by a term: its entry, with its kind and tier, the USPS words that define it and the page they're on, its other names, postalref's own explanation where it has one, and when USPS ended or renamed it, each with USPS's words; /glossary/<words>, such as /glossary/mailer-id or /glossary/MID, gives the entries those words name, in the order search ranks them. /codes/<table>/<code>, such as /codes/service-type-codes/055, gives a code's row as USPS prints it in the newest edition that lists it, the editions that list it and its history. /documents/<id> gives any document postalref holds, page by page as extracted, to quote, and /documents lists them. Any other path is a page of the site, given as its Markdown: a product page (/products/<id>), a guide (/guides/<id>), a code table's home (/codes/<table>), a case (/cases/<id>), a spec (/specs/<id>), a topic (/topics/<id>) or /changes. Quote whole sentences, word for word. A definition's words cite its document and page, and its `read` names the document and page to read for the sentences around them. A document's `text`, or a `found` context, which shows the whole sentence around the words or the lead-in with the list it opens, cites the revision's sha256, the PDF page and the words exactly; read another page `found` lists by its `pdf` number, or a part by its number, as `page`. When the text ends mid-sentence or mid-list, `continued` gives the rest of it from `next`, cited by its own page; when it ends mid-table, or a list goes on past `continued`, read `next`. A text without pages, a web page or a product page, reads in parts, and a quote from one cites no page.
| Parameter | Type | Description |
|---|---|---|
| find | string | With /documents/<id>: words to find, as one phrase, or when no page has the phrase, each word anywhere on a page. Without `page`, the text read is the first pages that have them. |
| page | integer | With /documents/<id>: the first PDF page, sheet or part to read, counting from 1; absent with `find`, the pages that have the words. With /documents: the page of the list, 100 documents a page. |
| path * | string | A path of postalref.com, as search and grep give each hit's `path`, or a page's address on the site: /glossary/mid, /glossary/mailer-id, /codes/service-type-codes/055, /documents/pub-199, /documents, /products/mid. |
| pages | integer | With /documents/<id>: how many to read, up to 5; 1 when absent. |
| revision | string | With /documents/<id>: a revision's sha256, or its slug, such as 2026-07-02. The newest when absent. |
{
"name": "read",
"title": "Read a page of postalref.com",
"description": "Read a page of postalref.com by its path. /glossary/<id> gives what USPS means by a term: its entry, with its kind and tier, the USPS words that define it and the page they're on, its other names, postalref's own explanation where it has one, and when USPS ended or renamed it, each with USPS's words; /glossary/<words>, such as /glossary/mailer-id or /glossary/MID, gives the entries those words name, in the order search ranks them. /codes/<table>/<code>, such as /codes/service-type-codes/055, gives a code's row as USPS prints it in the newest edition that lists it, the editions that list it and its history. /documents/<id> gives any document postalref holds, page by page as extracted, to quote, and /documents lists them. Any other path is a page of the site, given as its Markdown: a product page (/products/<id>), a guide (/guides/<id>), a code table's home (/codes/<table>), a case (/cases/<id>), a spec (/specs/<id>), a topic (/topics/<id>) or /changes. Quote whole sentences, word for word. A definition's words cite its document and page, and its `read` names the document and page to read for the sentences around them. A document's `text`, or a `found` context, which shows the whole sentence around the words or the lead-in with the list it opens, cites the revision's sha256, the PDF page and the words exactly; read another page `found` lists by its `pdf` number, or a part by its number, as `page`. When the text ends mid-sentence or mid-list, `continued` gives the rest of it from `next`, cited by its own page; when it ends mid-table, or a list goes on past `continued`, read `next`. A text without pages, a web page or a product page, reads in parts, and a quote from one cites no page.",
"inputSchema": {
"type": "object",
"required": [
"path"
],
"properties": {
"find": {
"type": "string",
"maxLength": 200,
"description": "With /documents/<id>: words to find, as one phrase, or when no page has the phrase, each word anywhere on a page. Without `page`, the text read is the first pages that have them."
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "With /documents/<id>: the first PDF page, sheet or part to read, counting from 1; absent with `find`, the pages that have the words. With /documents: the page of the list, 100 documents a page."
},
"path": {
"type": "string",
"maxLength": 200,
"description": "A path of postalref.com, as search and grep give each hit's `path`, or a page's address on the site: /glossary/mid, /glossary/mailer-id, /codes/service-type-codes/055, /documents/pub-199, /documents, /products/mid."
},
"pages": {
"type": "integer",
"maximum": 5,
"minimum": 1,
"description": "With /documents/<id>: how many to read, up to 5; 1 when absent."
},
"revision": {
"type": "string",
"maxLength": 64,
"description": "With /documents/<id>: a revision's sha256, or its slug, such as 2026-07-02. The newest when absent."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"path"
],
"properties": {
"code": {
"type": "object",
"required": [
"matches"
],
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"table",
"code",
"listed",
"rows",
"editions",
"history"
],
"properties": {
"code": {
"type": "string"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"required": [
"passage",
"revision",
"place",
"cells",
"checked",
"references"
],
"properties": {
"cells": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value"
],
"properties": {
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"notes": {
"type": "array",
"items": {
"type": "object",
"required": [
"mark",
"text",
"revision",
"page"
],
"properties": {
"mark": {
"type": "string",
"minLength": 1
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"text": {
"type": "string",
"minLength": 1
},
"revision": {
"type": "string"
}
},
"additionalProperties": true
}
},
"place": {
"anyOf": [
{
"type": "object",
"required": [
"_tag",
"page"
],
"properties": {
"_tag": {
"enum": [
"Text"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
},
"section": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"page",
"table"
],
"properties": {
"_tag": {
"enum": [
"TableRow"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"sheet",
"row"
],
"properties": {
"row": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"_tag": {
"enum": [
"SheetRow"
],
"type": "string"
},
"sheet": {
"type": "string"
}
},
"additionalProperties": true
}
]
},
"filled": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value",
"from"
],
"properties": {
"from": {
"type": "string"
},
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"checked": {
"type": "boolean"
},
"passage": {
"type": "string"
},
"revision": {
"type": "string"
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"table",
"code"
],
"properties": {
"row": {
"type": "object",
"required": [
"passage",
"cells",
"checked"
],
"properties": {
"cells": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"value"
],
"properties": {
"value": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
},
"checked": {
"type": "boolean"
},
"passage": {
"type": "string"
}
},
"additionalProperties": true
},
"code": {
"type": "string"
},
"table": {
"type": "string"
},
"column": {
"type": "string"
},
"removed": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"table": {
"type": "object",
"required": [
"slug",
"name",
"document",
"edition"
],
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"edition": {
"type": "string"
},
"document": {
"type": "string"
}
},
"additionalProperties": true
},
"listed": {
"type": "boolean"
},
"history": {
"type": "object",
"required": [
"series",
"code",
"first",
"events"
],
"properties": {
"code": {
"type": "string"
},
"first": {
"type": "object",
"required": [
"date",
"fid",
"how",
"rows"
],
"properties": {
"fid": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"how": {
"enum": [
"listed",
"added"
],
"type": "string"
},
"date": {
"type": "string"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"additionalProperties": true
},
"events": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"fid",
"change"
],
"properties": {
"fid": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"row": {
"type": "string"
},
"date": {
"type": "string"
},
"diff": {
"type": "string"
},
"cells": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"marks": {
"type": "string"
},
"change": {
"enum": [
"added",
"removed",
"changed",
"retired",
"unchecked",
"disagreement"
],
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"before",
"after"
],
"properties": {
"after": {
"type": "string"
},
"before": {
"type": "string"
},
"column": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"series": {
"type": "string"
}
},
"additionalProperties": true
},
"removed": {
"type": "string"
},
"editions": {
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"revision",
"place",
"checked"
],
"properties": {
"date": {
"type": "string"
},
"place": {
"anyOf": [
{
"type": "object",
"required": [
"_tag",
"page"
],
"properties": {
"_tag": {
"enum": [
"Text"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
},
"section": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"page",
"table"
],
"properties": {
"_tag": {
"enum": [
"TableRow"
],
"type": "string"
},
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"table": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"sheet",
"row"
],
"properties": {
"row": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"_tag": {
"enum": [
"SheetRow"
],
"type": "string"
},
"sheet": {
"type": "string"
}
},
"additionalProperties": true
}
]
},
"checked": {
"type": "boolean"
},
"revision": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
},
"list": {
"type": "object",
"required": [
"total",
"documents"
],
"properties": {
"next": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"documents": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"path"
],
"properties": {
"id": {
"type": "string"
},
"path": {
"type": "string"
},
"title": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
},
"path": {
"type": "string"
},
"term": {
"type": "object",
"required": [
"query",
"total",
"entries"
],
"properties": {
"match": {
"enum": [
"definition"
],
"type": "string"
},
"query": {
"type": "string"
},
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"aka",
"kind",
"tier",
"cite"
],
"properties": {
"id": {
"type": "string"
},
"is": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"_tag",
"node"
],
"properties": {
"_tag": {
"enum": [
"Product"
],
"type": "string"
},
"node": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"node"
],
"properties": {
"_tag": {
"enum": [
"Document"
],
"type": "string"
},
"node": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"spec"
],
"properties": {
"_tag": {
"enum": [
"Spec"
],
"type": "string"
},
"spec": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"spec",
"key"
],
"properties": {
"key": {
"type": "string"
},
"_tag": {
"enum": [
"Field"
],
"type": "string"
},
"spec": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"table"
],
"properties": {
"_tag": {
"enum": [
"Table"
],
"type": "string"
},
"table": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"_tag",
"table",
"code"
],
"properties": {
"_tag": {
"enum": [
"Code"
],
"type": "string"
},
"code": {
"type": "string"
},
"table": {
"type": "string"
}
},
"additionalProperties": true
}
]
}
},
"aka": {
"type": "array",
"items": {
"type": "string"
}
},
"cite": {
"type": "string"
},
"kind": {
"enum": [
"mail-class",
"extra-service",
"service",
"program",
"system",
"file",
"identifier",
"document",
"facility",
"container",
"role",
"term"
],
"type": "string"
},
"name": {
"type": "string"
},
"page": {
"type": "string"
},
"tier": {
"enum": [
"core",
"reference"
],
"type": "string"
},
"former": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"quote",
"document",
"url"
],
"properties": {
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"page": {
"type": "string"
},
"read": {
"type": "object",
"required": [
"document"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"document": {
"type": "string"
}
},
"additionalProperties": true
},
"quote": {
"type": "string"
},
"document": {
"type": "string"
}
},
"additionalProperties": true
}
},
"retired": {
"type": "object",
"required": [
"quote",
"document",
"url"
],
"properties": {
"by": {
"type": "string"
},
"on": {
"type": "string"
},
"url": {
"type": "string"
},
"page": {
"type": "string"
},
"read": {
"type": "object",
"required": [
"document"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"document": {
"type": "string"
}
},
"additionalProperties": true
},
"quote": {
"type": "string"
},
"document": {
"type": "string"
}
},
"additionalProperties": true
},
"explained": {
"type": "string"
},
"definition": {
"type": "object",
"required": [
"quote",
"document",
"url"
],
"properties": {
"url": {
"type": "string"
},
"page": {
"type": "string"
},
"read": {
"type": "object",
"required": [
"document"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"document": {
"type": "string"
}
},
"additionalProperties": true
},
"dated": {
"type": "string"
},
"quote": {
"type": "string"
},
"document": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
},
"document": {
"type": "object",
"required": [
"document",
"revision",
"revisions",
"parts",
"text"
],
"properties": {
"next": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"text": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"text"
],
"properties": {
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"text": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": true
}
},
"found": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"context"
],
"properties": {
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"label": {
"type": "string"
},
"context": {
"type": "string"
}
},
"additionalProperties": true
}
},
"match": {
"enum": [
"phrase",
"words"
],
"type": "string"
},
"parts": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"document": {
"type": "object",
"required": [
"slug",
"name"
],
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"additionalProperties": true
},
"revision": {
"anyOf": [
{
"type": "object",
"required": [
"sha256",
"document",
"slug",
"fid",
"file",
"original",
"uploaded",
"fetched",
"format"
],
"properties": {
"fid": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"file": {
"type": "string"
},
"slug": {
"type": "string"
},
"dated": {
"type": "string"
},
"pages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"copies": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"format": {
"enum": [
"pdf",
"xlsx"
],
"type": "string"
},
"sha256": {
"type": "string"
},
"edition": {
"type": "string"
},
"fetched": {
"type": "string"
},
"document": {
"type": "string"
},
"original": {
"type": "string"
},
"uploaded": {
"type": "string"
},
"effective": {
"type": "string"
},
"supersededBy": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"sha256",
"document",
"slug",
"from",
"format",
"original",
"fetched"
],
"properties": {
"date": {
"type": "string"
},
"from": {
"enum": [
"postalpro",
"product",
"download"
],
"type": "string"
},
"slug": {
"type": "string"
},
"pages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"format": {
"type": "string"
},
"sha256": {
"type": "string"
},
"fetched": {
"type": "string"
},
"document": {
"type": "string"
},
"original": {
"type": "string"
}
},
"additionalProperties": true
}
]
},
"continued": {
"type": "object",
"required": [
"label",
"text"
],
"properties": {
"page": {
"type": "object",
"required": [
"pdf"
],
"properties": {
"pdf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
},
"text": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": true
},
"revisions": {
"type": "array",
"items": {
"type": "object",
"required": [
"sha256",
"slug",
"format"
],
"properties": {
"slug": {
"type": "string"
},
"format": {
"type": "string"
},
"sha256": {
"type": "string"
},
"uploaded": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
},
"markdown": {
"type": "string"
}
},
"additionalProperties": true
},
"annotations": {
"title": "Read a page of postalref.com",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Search the text of every document postalref holds, or of one, for the pages that say the words, best first: those that say them as a phrase, then by how much of the page they are and how many of them it says side by side or close together, a table of contents last. A court's filing or a Justice Department release about a fraud case comes after USPS's own pages when one of those says every word, as Publication 52 and a release about a bulk mail fraud both say bulk mail permit; a case's name finds its records first. A document gives at most three pages while other documents' pages fill the list, and `more` gives each document a hit is from that has more pages with the words, and how many: grep again with /documents/<id> as `path` to rank only its pages. A page needn't have the words a question asks with, such as how, get or take. Each word is found in its forms, and a name also as the registry's other names for it, BCG for Business Customer Gateway or Post Office Box for PO Box, and a size as 4x6 or 4 x 6; a hit another wording found gives it as `by`. Each hit gives the path and page read reads, and the passage that says most of the words. Use it when no title names what you're looking for, as for a price in the Mail Classification Schedule or a rule in a DMM chapter. With /documents as `path`, it searches every document on PostalPro by title and file name instead, with its page and newest file, and the product pages and downloads postalref holds by title; each one postalref holds the text of carries the path read takes. A hit's `context` is a whole sentence, list or row of the page unless it starts or ends with …: quote it with the hit's `id` and `page`, or read its `path` at that `page` for the sentences around it. When no hit answers, grep again with the words an answer would say. A title says only that USPS publishes a document: read one grep lists to learn what it says.
| Parameter | Type | Description |
|---|---|---|
| path | string | Where to look: /documents/<id>, one document's pages, every one that says the words up to `limit`; or /documents, the titles of every PostalPro document and of the documents postalref holds. Every page of every document postalref holds when absent. |
| limit | integer | At most this many; 10 when absent. |
| query * | string | Words a page says: a price, a rule, a size, a name. Each word is found in its forms: one or many, -ed, -ing, -able, -ous. With /documents: words from a document's title or file name. |
| topic | string | With /documents: only documents a model put under this topic. |
{
"name": "grep",
"title": "Search the documents",
"description": "Search the text of every document postalref holds, or of one, for the pages that say the words, best first: those that say them as a phrase, then by how much of the page they are and how many of them it says side by side or close together, a table of contents last. A court's filing or a Justice Department release about a fraud case comes after USPS's own pages when one of those says every word, as Publication 52 and a release about a bulk mail fraud both say bulk mail permit; a case's name finds its records first. A document gives at most three pages while other documents' pages fill the list, and `more` gives each document a hit is from that has more pages with the words, and how many: grep again with /documents/<id> as `path` to rank only its pages. A page needn't have the words a question asks with, such as how, get or take. Each word is found in its forms, and a name also as the registry's other names for it, BCG for Business Customer Gateway or Post Office Box for PO Box, and a size as 4x6 or 4 x 6; a hit another wording found gives it as `by`. Each hit gives the path and page read reads, and the passage that says most of the words. Use it when no title names what you're looking for, as for a price in the Mail Classification Schedule or a rule in a DMM chapter. With /documents as `path`, it searches every document on PostalPro by title and file name instead, with its page and newest file, and the product pages and downloads postalref holds by title; each one postalref holds the text of carries the path read takes. A hit's `context` is a whole sentence, list or row of the page unless it starts or ends with …: quote it with the hit's `id` and `page`, or read its `path` at that `page` for the sentences around it. When no hit answers, grep again with the words an answer would say. A title says only that USPS publishes a document: read one grep lists to learn what it says.",
"inputSchema": {
"type": "object",
"required": [
"query"
],
"properties": {
"path": {
"type": "string",
"maxLength": 200,
"description": "Where to look: /documents/<id>, one document's pages, every one that says the words up to `limit`; or /documents, the titles of every PostalPro document and of the documents postalref holds. Every page of every document postalref holds when absent."
},
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "At most this many; 10 when absent."
},
"query": {
"type": "string",
"maxLength": 200,
"description": "Words a page says: a price, a rule, a size, a name. Each word is found in its forms: one or many, -ed, -ing, -able, -ous. With /documents: words from a document's title or file name."
},
"topic": {
"enum": [
"mailing",
"shipping",
"address-quality",
"visibility",
"promotions",
"operations",
"accounts",
"industry",
"international",
"other"
],
"type": "string",
"description": "With /documents: only documents a model put under this topic."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"pages": {
"type": "object",
"required": [
"query",
"total",
"match",
"hits"
],
"properties": {
"hits": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"path",
"title",
"page",
"label",
"phrase",
"context"
],
"properties": {
"by": {
"type": "string"
},
"id": {
"type": "string"
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"path": {
"type": "string"
},
"label": {
"type": "string"
},
"title": {
"type": "string"
},
"phrase": {
"type": "boolean"
},
"context": {
"type": "string"
},
"printed": {
"type": "string"
}
},
"additionalProperties": true
}
},
"more": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"pages"
],
"properties": {
"id": {
"type": "string"
},
"pages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": true
}
},
"match": {
"enum": [
"all",
"some"
],
"type": "string"
},
"query": {
"type": "string"
},
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
}
},
"additionalProperties": true
},
"titles": {
"type": "object",
"required": [
"query",
"total",
"documents"
],
"properties": {
"query": {
"type": "string"
},
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"documents": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"nid",
"title",
"kinds",
"changed",
"url"
],
"properties": {
"id": {
"type": "string"
},
"nid": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"url": {
"type": "string"
},
"date": {
"type": "string"
},
"file": {
"type": "object",
"required": [
"name",
"link"
],
"properties": {
"link": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": true
},
"path": {
"type": "string"
},
"slug": {
"type": "string"
},
"kinds": {
"type": "array",
"items": {
"type": "string"
}
},
"title": {
"type": "string"
},
"topic": {
"enum": [
"mailing",
"shipping",
"address-quality",
"visibility",
"promotions",
"operations",
"accounts",
"industry",
"international",
"other"
],
"type": "string"
},
"changed": {
"type": "string"
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"id",
"path",
"title",
"url",
"from",
"fetched"
],
"properties": {
"id": {
"type": "string"
},
"nid": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"url": {
"type": "string"
},
"from": {
"enum": [
"product",
"download"
],
"type": "string"
},
"path": {
"type": "string"
},
"title": {
"type": "string"
},
"fetched": {
"type": "string"
}
},
"additionalProperties": true
}
]
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"annotations": {
"title": "Search the documents",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}postalref answers from USPS's PostalPro documents, each answer with the passage that says it. decode reads a package barcode or tracking number, or a letter's or flat's Intelligent Mail barcode; lookup gives a code's row and history; diff says what changed between editions; search finds codes, terms and specs, each with its path on postalref.com; read reads a path: what USPS means by a term at /glossary/<id>, a code at /codes/<table>/<code>, a held document's text to quote at /documents/<id>, the documents postalref holds at /documents, and any other page of the site; grep finds the pages of held documents that say some words, or with /documents as its path, any PostalPro document by its title. To answer a question, read its main term at /glossary/<words>, then grep the words an answer would say, such as a price, a rule or a name, or grep /documents for what USPS publishes on it, and read the pages they give. Cite each sentence of an answer from words you read, copied exactly, with the document's id, the revision's sha256 and the PDF page, and leave out what no words you read say. When a page ends mid-sentence or mid-list, read `next`. Before saying postalref doesn't hold an answer, grep again with other words, such as the term's other names and abbreviations, and read the documents a search lists.
Names, descriptions and schemas were written by the server and are shown as data.