freightapis 1.0.0__tar.gz

freightapis-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreightAPIs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

freightapis-1.0.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: freightapis
+Version: 1.0.0
+Summary: Python SDK for FreightAPIs — NMFC freight classification, multi-carrier terminal locations, and global seaport data.
+Author: FreightAPIs
+License: MIT
+Project-URL: Homepage, https://freightapis.dev/docs
+Project-URL: Documentation, https://freightapis.dev/docs
+Project-URL: Repository, https://github.com/buildinpublichub/freightapis.dev
+Keywords: freight,nmfc,ltl,shipping,logistics,carrier,terminal,seaport,api
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: requests
+Requires-Dist: requests>=2; extra == "requests"
+Dynamic: license-file
+
+# freightapis (Python)
+
+Tiny client for [FreightAPIs](https://freightapis.dev) — NMFC freight classification, multi-carrier terminal locations, and global seaports. Uses `requests` if installed, else the stdlib (zero required dependencies).
+
+```bash
+pip install freightapis
+```
+
+## Usage
+
+```python
+import os
+from freightapis import FreightAPIs
+
+fa = FreightAPIs(os.environ["FREIGHTAPIS_KEY"])
+
+# Carrier locations
+ga = fa.carrier_by_state_or_zip("estes", state="GA")
+search = fa.carrier_search("saia", "atlanta")
+cov = fa.carrier_coverage("abf", state="AR")
+batch = fa.carrier_batch("usps", {"states": ["NY", "NJ"]})
+
+# Seaports
+cn = fa.ports_by_country("CN")
+sh = fa.port("CNSHA")
+near = fa.ports_nearby(31.2, 121.5, radius=200)
+cosco = fa.ports_by_company("COSCO")
+
+# NMFC classification (Pro plan)
+cls = fa.nmfc_search("furniture")
+art = fa.article("63321")
+dens = fa.density({
+    "dimensionType": "Inch", "weightType": "Pound", "resultUnitType": "PoundsPerCubicFeet",
+    "unitDimensions": [{"HandlingUnitCount": 1, "length": 48, "width": 40, "height": 48, "handlingUnitWeight": 500}],
+})
+
+# Any endpoint not covered by a helper:
+days = fa.request("GET", "/api/abf-location/service-days", query={"zip": "72401"})
+```
+
+## Errors
+
+Non-2xx responses raise `FreightAPIError` with `.status` and `.body`:
+
+```python
+from freightapis import FreightAPIError
+try:
+    fa.article("does-not-exist")
+except FreightAPIError as e:
+    print(e.status, e.body)
+```
+
+API reference: https://freightapis.dev/docs · MIT licensed.

freightapis-1.0.0/README.md

@@ -0,0 +1,53 @@
+# freightapis (Python)
+
+Tiny client for [FreightAPIs](https://freightapis.dev) — NMFC freight classification, multi-carrier terminal locations, and global seaports. Uses `requests` if installed, else the stdlib (zero required dependencies).
+
+```bash
+pip install freightapis
+```
+
+## Usage
+
+```python
+import os
+from freightapis import FreightAPIs
+
+fa = FreightAPIs(os.environ["FREIGHTAPIS_KEY"])
+
+# Carrier locations
+ga = fa.carrier_by_state_or_zip("estes", state="GA")
+search = fa.carrier_search("saia", "atlanta")
+cov = fa.carrier_coverage("abf", state="AR")
+batch = fa.carrier_batch("usps", {"states": ["NY", "NJ"]})
+
+# Seaports
+cn = fa.ports_by_country("CN")
+sh = fa.port("CNSHA")
+near = fa.ports_nearby(31.2, 121.5, radius=200)
+cosco = fa.ports_by_company("COSCO")
+
+# NMFC classification (Pro plan)
+cls = fa.nmfc_search("furniture")
+art = fa.article("63321")
+dens = fa.density({
+    "dimensionType": "Inch", "weightType": "Pound", "resultUnitType": "PoundsPerCubicFeet",
+    "unitDimensions": [{"HandlingUnitCount": 1, "length": 48, "width": 40, "height": 48, "handlingUnitWeight": 500}],
+})
+
+# Any endpoint not covered by a helper:
+days = fa.request("GET", "/api/abf-location/service-days", query={"zip": "72401"})
+```
+
+## Errors
+
+Non-2xx responses raise `FreightAPIError` with `.status` and `.body`:
+
+```python
+from freightapis import FreightAPIError
+try:
+    fa.article("does-not-exist")
+except FreightAPIError as e:
+    print(e.status, e.body)
+```
+
+API reference: https://freightapis.dev/docs · MIT licensed.

freightapis-1.0.0/freightapis.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: freightapis
+Version: 1.0.0
+Summary: Python SDK for FreightAPIs — NMFC freight classification, multi-carrier terminal locations, and global seaport data.
+Author: FreightAPIs
+License: MIT
+Project-URL: Homepage, https://freightapis.dev/docs
+Project-URL: Documentation, https://freightapis.dev/docs
+Project-URL: Repository, https://github.com/buildinpublichub/freightapis.dev
+Keywords: freight,nmfc,ltl,shipping,logistics,carrier,terminal,seaport,api
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: requests
+Requires-Dist: requests>=2; extra == "requests"
+Dynamic: license-file
+
+# freightapis (Python)
+
+Tiny client for [FreightAPIs](https://freightapis.dev) — NMFC freight classification, multi-carrier terminal locations, and global seaports. Uses `requests` if installed, else the stdlib (zero required dependencies).
+
+```bash
+pip install freightapis
+```
+
+## Usage
+
+```python
+import os
+from freightapis import FreightAPIs
+
+fa = FreightAPIs(os.environ["FREIGHTAPIS_KEY"])
+
+# Carrier locations
+ga = fa.carrier_by_state_or_zip("estes", state="GA")
+search = fa.carrier_search("saia", "atlanta")
+cov = fa.carrier_coverage("abf", state="AR")
+batch = fa.carrier_batch("usps", {"states": ["NY", "NJ"]})
+
+# Seaports
+cn = fa.ports_by_country("CN")
+sh = fa.port("CNSHA")
+near = fa.ports_nearby(31.2, 121.5, radius=200)
+cosco = fa.ports_by_company("COSCO")
+
+# NMFC classification (Pro plan)
+cls = fa.nmfc_search("furniture")
+art = fa.article("63321")
+dens = fa.density({
+    "dimensionType": "Inch", "weightType": "Pound", "resultUnitType": "PoundsPerCubicFeet",
+    "unitDimensions": [{"HandlingUnitCount": 1, "length": 48, "width": 40, "height": 48, "handlingUnitWeight": 500}],
+})
+
+# Any endpoint not covered by a helper:
+days = fa.request("GET", "/api/abf-location/service-days", query={"zip": "72401"})
+```
+
+## Errors
+
+Non-2xx responses raise `FreightAPIError` with `.status` and `.body`:
+
+```python
+from freightapis import FreightAPIError
+try:
+    fa.article("does-not-exist")
+except FreightAPIError as e:
+    print(e.status, e.body)
+```
+
+API reference: https://freightapis.dev/docs · MIT licensed.

freightapis-1.0.0/freightapis.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+freightapis.py
+pyproject.toml
+freightapis.egg-info/PKG-INFO
+freightapis.egg-info/SOURCES.txt
+freightapis.egg-info/dependency_links.txt
+freightapis.egg-info/requires.txt
+freightapis.egg-info/top_level.txt

freightapis-1.0.0/freightapis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

freightapis-1.0.0/freightapis.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[requests]
+requests>=2

freightapis-1.0.0/freightapis.egg-info/top_level.txt

@@ -0,0 +1 @@
+freightapis

freightapis-1.0.0/freightapis.py

@@ -0,0 +1,142 @@
+"""
+FreightAPIs Python SDK — a tiny dependency-light client for the FreightAPIs
+REST API (https://freightapis.dev).
+
+Uses `requests` if available, else falls back to the stdlib `urllib`, so it
+works with zero third-party dependencies.
+
+Get an API key at https://freightapis.dev/account. Full reference:
+https://freightapis.dev/docs  ·  OpenAPI: https://freightapis.dev/openapi.yaml
+
+MIT licensed.
+"""
+from __future__ import annotations
+
+import json as _json
+from typing import Any, Optional, Mapping
+from urllib.parse import urlencode
+
+DEFAULT_BASE_URL = "https://freightapis.dev"
+
+try:
+    import requests as _requests  # type: ignore
+except ImportError:  # pragma: no cover
+    _requests = None
+
+
+class FreightAPIError(Exception):
+    def __init__(self, message: str, status: int, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class FreightAPIs:
+    """Client for the FreightAPIs REST API."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL):
+        if not api_key:
+            raise ValueError("FreightAPIs: an API key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    # ── transport ────────────────────────────────────────────────────────
+    def _request(self, method: str, path: str, query: Optional[Mapping[str, Any]] = None,
+                 body: Any = None) -> Any:
+        url = self.base_url + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None}
+            if clean:
+                url += "?" + urlencode(clean)
+        headers = {"X-API-Key": self.api_key, "Accept": "application/json"}
+        payload = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            payload = _json.dumps(body)
+
+        if _requests is not None:
+            resp = _requests.request(method, url, headers=headers, data=payload)
+            status, text = resp.status_code, resp.text
+        else:
+            import urllib.request
+            import urllib.error
+            req = urllib.request.Request(
+                url, data=payload.encode() if payload else None,
+                headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req) as r:
+                    status, text = r.status, r.read().decode()
+            except urllib.error.HTTPError as e:
+                status, text = e.code, e.read().decode()
+
+        try:
+            data = _json.loads(text) if text else None
+        except ValueError:
+            data = text
+        if not (200 <= status < 300):
+            msg = (data.get("error") if isinstance(data, dict) else None) or f"HTTP {status}"
+            raise FreightAPIError(msg, status, data)
+        return data
+
+    # ── carrier locations ────────────────────────────────────────────────
+    def carrier_by_state_or_zip(self, carrier: str, *, state: Optional[str] = None,
+                                zip: Optional[str] = None, country: Optional[str] = None) -> Any:
+        return self._request("GET", f"/api/{carrier}-location",
+                             {"state": state, "zip": zip, "country": country})
+
+    def carrier_search(self, carrier: str, query: str, page: int = 1) -> Any:
+        return self._request("GET", f"/api/{carrier}-location/search", {"q": query, "page": page})
+
+    def carrier_coverage(self, carrier: str, *, state: Optional[str] = None) -> Any:
+        return self._request("GET", f"/api/{carrier}-location/coverage", {"state": state})
+
+    def carrier_batch(self, carrier: str, body: Mapping[str, Any]) -> Any:
+        return self._request("POST", f"/api/{carrier}-location/batch", body=body)
+
+    # ── seaports ──────────────────────────────────────────────────────────
+    def ports_by_country(self, country: str, page: int = 1) -> Any:
+        return self._request("GET", "/api/ports", {"country": country, "page": page})
+
+    def ports_search(self, query: str, page: int = 1) -> Any:
+        return self._request("GET", "/api/ports/search", {"q": query, "page": page})
+
+    def ports_by_company(self, company: str, page: int = 1) -> Any:
+        return self._request("GET", "/api/ports/by-company", {"company": company, "page": page})
+
+    def ports_nearby(self, lat: float, lng: float, *, radius: Optional[float] = None,
+                     page: Optional[int] = None) -> Any:
+        return self._request("GET", "/api/ports/nearby",
+                             {"lat": lat, "lng": lng, "radius": radius, "page": page})
+
+    def port(self, unlocode: str) -> Any:
+        return self._request("GET", f"/api/ports/{unlocode}")
+
+    def ports_batch(self, unlocodes: list[str]) -> Any:
+        return self._request("POST", "/api/ports/batch", body={"unlocodes": unlocodes})
+
+    # ── NMFC classification (Pro plan) ────────────────────────────────────
+    def nmfc_search(self, query: str, page: int = 1) -> Any:
+        return self._request("POST", "/api/search", body={"q": query, "page": page})
+
+    def article(self, num: Any) -> Any:
+        return self._request("GET", f"/api/article/{num}")
+
+    def rule(self, num: Any) -> Any:
+        return self._request("GET", f"/api/rule/{num}")
+
+    def package(self, num: Any) -> Any:
+        return self._request("GET", f"/api/package/{num}")
+
+    def history(self, num: Any) -> Any:
+        return self._request("GET", f"/api/history/{num}")
+
+    def density(self, body: Any) -> Any:
+        return self._request("POST", "/api/density", body=body)
+
+    def item680(self, type: str, body: Any) -> Any:
+        return self._request("POST", f"/api/item680/{type}", body=body)
+
+    # ── escape hatch ──────────────────────────────────────────────────────
+    def request(self, method: str, path: str, *, query: Optional[Mapping[str, Any]] = None,
+                body: Any = None) -> Any:
+        return self._request(method, path, query, body)

freightapis-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "freightapis"
+version = "1.0.0"
+description = "Python SDK for FreightAPIs — NMFC freight classification, multi-carrier terminal locations, and global seaport data."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["freight", "nmfc", "ltl", "shipping", "logistics", "carrier", "terminal", "seaport", "api"]
+authors = [{ name = "FreightAPIs" }]
+dependencies = []
+
+[project.optional-dependencies]
+requests = ["requests>=2"]
+
+[project.urls]
+Homepage = "https://freightapis.dev/docs"
+Documentation = "https://freightapis.dev/docs"
+Repository = "https://github.com/buildinpublichub/freightapis.dev"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["freightapis"]

freightapis-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+