{"id":15631369,"url":"https://github.com/jkeen/tracking_number","last_synced_at":"2025-10-08T19:10:45.178Z","repository":{"id":1270643,"uuid":"1209803","full_name":"jkeen/tracking_number","owner":"jkeen","description":"Identifies valid tracking numbers and a little bit more","archived":false,"fork":false,"pushed_at":"2025-08-21T19:21:34.000Z","size":400,"stargazers_count":204,"open_issues_count":2,"forks_count":53,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-08-21T21:54:06.649Z","etag":null,"topics":["amazon","detection","dhl","fedex","ontrac","shipping","tracking-number","ups","usps"],"latest_commit_sha":null,"homepage":"http://github.com/jkeen/tracking_number","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jkeen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2010-12-31T00:07:39.000Z","updated_at":"2025-08-21T19:21:35.000Z","dependencies_parsed_at":"2024-06-18T21:15:24.722Z","dependency_job_id":"cafdf9fd-e7d9-4236-a1e7-bbceccdddea0","html_url":"https://github.com/jkeen/tracking_number","commit_stats":{"total_commits":160,"total_committers":21,"mean_commits":7.619047619047619,"dds":"0.26875000000000004","last_synced_commit":"04efeb549831657850165a22a4c1494caad11c6e"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/jkeen/tracking_number","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkeen%2Ftracking_number","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkeen%2Ftracking_number/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkeen%2Ftracking_number/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkeen%2Ftracking_number/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jkeen","download_url":"https://codeload.github.com/jkeen/tracking_number/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkeen%2Ftracking_number/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000701,"owners_count":26082805,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon","detection","dhl","fedex","ontrac","shipping","tracking-number","ups","usps"],"created_at":"2024-10-03T10:40:05.424Z","updated_at":"2025-10-08T19:10:45.156Z","avatar_url":"https://github.com/jkeen.png","language":"Ruby","funding_links":["https://www.buymeacoffee.com/jeffkeen"],"categories":[],"sub_categories":[],"readme":"[![Ruby](https://github.com/jkeen/tracking_number/actions/workflows/ruby.yml/badge.svg)](https://github.com/jkeen/tracking_number/actions/workflows/ruby.yml)\n[![Gem Version](https://badge.fury.io/rb/tracking_number.svg)](https://badge.fury.io/rb/tracking_number)\n[![Gem](https://img.shields.io/gem/dt/tracking_number.svg)]()\n\n\u003e Hey there tracking number enthusiast! I don't use this project in any production capacity, and really never have. I am not a tracking number expert, and I don't have inside connections to a shipping company—I'm just a guy that once tried to make a package tracking app and this gem is all that survived. When I have absolutely nothing to do it's kinda fun to tinker with, but time has become more and more of a precious resource. Anyway, maintaining this is thankless work, and if this project has been useful for you I sure would appreciate a cup or two of coffee slid my way as a token of appreciation. A PR would also be nice. \n\u003e \n\u003e \u003ca href=\"https://www.buymeacoffee.com/jeffkeen\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: auto !important;width: 150px !important;\" \u003e\u003c/a\u003e\n\n## Tracking Number (v1.x)\n\nThis gem identifies valid tracking numbers and can tell you a little bit about the shipment just from the number—there's quite a bit of info tucked away into those numbers, it turns out.\n\nIt detects tracking numbers from UPS, FedEx, DHL, USPS, OnTrac, Amazon Logistics, and 160+ countries national postal services (S10 standard).\n\nThis gem does not do tracking. That is left up to you.\n\n#### New in 1.0\n\nStarting with the 1.0 release the specifications for detecting tracking numbers have been moved into a separate repository ([tracking_number_data](http://github.com/jkeen/tracking_number_data)) that this gem relies on. I did this so a) we can have a single place to document all tracking number types and it can be more of a crowdsourced effort, and b) so clients can be written in other languages easier.\n\n## Usage\n\n#### Checking an individual tracking number\n```ruby\nt = TrackingNumber.new(\"MYSTERY_TRACKING_NUMBER\")\n# =\u003e #\u003cTrackingNumber::Unknown MYSTERY_TRACKING_NUMBER\u003e\nt.valid? #=\u003e false\n\nt = TrackingNumber.new(\"1Z879E930346834440\")\n# =\u003e #\u003cTrackingNumber::UPS 1Z879E930346834440\u003e\nt.valid? #=\u003e true\n```\n\n#### Searching a block of text\nThis will return valid tracking numbers contained within a block of text.\n\n```ruby\nTrackingNumber.search(\"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, 1Z879E930346834440 nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute 9611020987654312345672 dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\")\n\n#=\u003e [#\u003cTrackingNumber::UPS 1Z879E930346834440\u003e, #\u003cTrackingNumber::FedExGround96 9611020987654312345672\u003e]\n```\n\n#### Courier Info\nAs of 1.0, the possible courier codes are `[:usps, :fedex, :ups, :ontrac, :dhl, :amazon, :s10, :unknown]`. S10 is the international standard used by local government post offices. When packages are shipped internationally via normal post, it's usually an S10 number.\n\n```ruby\nt = TrackingNumber.new(\"1Z879E930346834440\")\n# =\u003e #\u003cTrackingNumber::UPS 1Z879E930346834440\u003e\n\nt.valid? #=\u003e true\nt.courier_code #=\u003e :ups\nt.courier_name #=\u003e \"UPS\"\n\n\nt = TrackingNumber.new(\"RB123456785GB\")\nt.courier_name #=\u003e \"Royal Mail Group plc\"\nt.courier_code #=\u003e :s10\n\nt = TrackingNumber.new(\"RB123456785US\")\nt.courier_name #=\u003e \"United States Postal Service\"\n```\n\n#### Service Type\nSome tracking numbers indicate their service type\n\n```ruby\nt = TrackingNumber.new(\"1Z879E930346834440\")\nt.service_type #=\u003e \"UPS United States Ground\"\"\n\nt = TrackingNumber.new(\"1ZXX3150YW44070023\")\nt.service_type #=\u003e \"UPS SurePost - Delivered by the USPS\"\n\nt = TrackingNumber.new(\"RB123456785US\")\nt.service_type #=\u003e \"Letter Post Registered\"\n```\n\n#### Shipper ID\nSome tracking numbers indicate information about their package\n```ruby\nt = TrackingNumber.new(\"1Z6072AF0320751583\")\nt.shipper_id #=\u003e \"6072AF\" \u003c-- this is Target\n```\n\n#### Destination Zip\nSome tracking numbers indicate their destination\n\n```ruby\nt = TrackingNumber.new(\"1001901781990001000300617767839437\")\nt.destination_zip #=\u003e \"10003\"\n```\n\n#### Package Info\nSome tracking numbers indicate information about their package\n\n```ruby\nt = TrackingNumber.new(\"012345000000002\")\nt.package_type #=\u003e \"case/carton\"\n```\n\n#### Tracking URL\nGet the tracking url from the shipper\n```ruby\nt = TrackingNumber.new(\"1Z6072AF0320751583\")\nt.tracking_url #=\u003e \"\"https://wwwapps.ups.com/WebTracking/track?track=yes\u0026trackNums=1Z6072AF0320751583\"\n```\n\n#### All the info we have\nGet a object of all the info we have on the thing\n```ruby\nt = TrackingNumber.new(\"1Z6072AF0320751583\")\nt.info #=\u003e  @courier=#\u003cTrackingNumber::Info:0x000000010a45fed8 @code=:ups, @name=\"UPS\"\u003e,\n       #    @decode={:serial_number=\u003e\"6072AF032075158\", :shipper_id=\u003e\"6072AF\", :service_type=\u003e\"03\", :package_id=\u003e\"2075158\", :check_digit=\u003e\"3\"},\n       #    @destination_zip=nil,\n       #    @package_type=nil,\n       #    @partners=nil,\n       #    @service_description=nil,\n       #    @service_type=\"UPS United States Ground\",\n       #    @shipper_id=\"6072AF\",\n       #    @tracking_url=\"https://wwwapps.ups.com/WebTracking/track?track=yes\u0026trackNums=1Z6072AF0320751583\"\u003e\n```\n\n#### Decoding\nMost tracking numbers have a format where each part of the number has meaning. `decode` splits up the number into its known named parts.\n```ruby\n  t = TrackingNumber.new(\"1Z879E930346834440\")\n  t.decode\n\n  #=\u003e {\n  #  :serial_number =\u003e \"879E93034683444\",\n  #  :shipper_id =\u003e \"879E93\",\n  #  :service_type =\u003e \"03\",\n  #  :package_id =\u003e \"4683444\",\n  #  :check_digit =\u003e \"0\"\n  # }   \n```\n\n#### Multiple shippers / Partnerships\nSome tracking numbers match multiple carriers, because they belong to multiple carriers. Some shipments like Fedex Smartpost contract the \"last mile\" out to USPS. \n\n```ruby\n  # Search defaults to only showing numbers that fulfill the carrier side of the relationship \n  # (if a partnership exists at all), as this is the end a consumer would most likely be interested in.\n\n  results = TrackingNumber.search('420112139261290983497923666238') \n  =\u003e [#\u003cTrackingNumber::USPS91:0x26ac0 420112139261290983497923666238\u003e]\n\n  all_results = TrackingNumber.search('420112139261290983497923666238', match: :all) \n  =\u003e [#\u003cTrackingNumber::FedExSmartPost:0x30624 420112139261290983497923666238\u003e, #\u003cTrackingNumber::USPS91:0x26ac0 420112139261290983497923666238\u003e]\n\n  tn = results.first\n  tn.shipper? #=\u003e false\n  tn.carrier? #=\u003e true\n  tn.partnership? #=\u003e true\n  tn.partners\n  #=\u003e \u003cstruct TrackingNumber::Base::PartnerStruct\n  #       shipper=#\u003cTrackingNumber::FedExSmartPost:0x30624 420112139261290983497923666238\u003e,\n  #       carrier=#\u003cTrackingNumber::USPS91:0x2f1fc 420112139261290983497923666238\u003e\u003e\n\n  tn.partners.shipper #=\u003e #\u003cTrackingNumber::FedExSmartPost:0x30624 420112139261290983497923666238\u003e\n  tn.partners.carrier == tn #=\u003e true\n```\n\n## ActiveModel validation\n\nFor Rails 3 (or any ActiveModel client), validate your fields as a tracking number:\n```ruby\nclass Shipment \u003c ActiveRecord::Base\n  validates :tracking, :tracking_number =\u003e true\nend\n```\nSometimes it's helpful to have a \"magic\" tracking number that isn't valid for any of the real carriers, and maybe will have other side effects (e.g., special treatment of a shipping email.)\n\n```ruby\nclass Shipment \u003c ActiveRecord::Base\n  validates :tracking, :tracking_number =\u003e { :except =\u003e 'magic-hand-delivery' }\nend\n```\n\n## Contributing to tracking_number\n* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet\n* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it\n* Fork the project\n* Start a feature/bugfix branch\n* Commit and push until you are happy with your contribution\n* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.\n* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.\n\n## Copyright\n\nCopyright (c) 2010-2021 Jeff Keen. See LICENSE.txt for\nfurther details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkeen%2Ftracking_number","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjkeen%2Ftracking_number","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkeen%2Ftracking_number/lists"}