blitz-api-py 0.3.0__tar.gz → 0.5.0__tar.gz

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.5.0](https://github.com/api-blitz/blitz-api-py/compare/v0.4.0...v0.5.0) (2026-06-18)
+
+
+### Features
+
+* scope client-side rate limiting per endpoint ([#13](https://github.com/api-blitz/blitz-api-py/issues/13)) ([de5308b](https://github.com/api-blitz/blitz-api-py/commit/de5308b6995edc68dd1e43a8554296b7de095df2))
+
+## [0.4.0](https://github.com/api-blitz/blitz-api-py/compare/v0.3.0...v0.4.0) (2026-06-17)
+
+
+### Features
+
+* add company department distribution endpoint and response models ([b64a6d9](https://github.com/api-blitz/blitz-api-py/commit/b64a6d9bada069206c77ee11c9f86fae01ef6baa))
+
+
+### Documentation
+
+* port JS SDK README upgrade (badges, billing note, TOC, example) ([#11](https://github.com/api-blitz/blitz-api-py/issues/11)) ([2276513](https://github.com/api-blitz/blitz-api-py/commit/2276513cdae4c23d4a1b50f59366e7156bf81019))
+
 ## [0.3.0](https://github.com/api-blitz/blitz-api-py/compare/v0.2.0...v0.3.0) (2026-06-04)
 
 

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blitz-api-py
-Version: 0.3.0
+Version: 0.5.0
 Summary: Typed Python SDK for the Blitz API — B2B data, search, and enrichment.
 Project-URL: Homepage, https://blitz-api.ai
 Project-URL: Documentation, https://docs.blitz-api.ai
@@ -31,6 +31,11 @@ Description-Content-Type: text/markdown
 
 # blitz-api-py
 
+[![PyPI version](https://img.shields.io/pypi/v/blitz-api-py.svg)](https://pypi.org/project/blitz-api-py/)
+[![types: py.typed](https://img.shields.io/badge/types-py.typed-blue.svg)](https://pypi.org/project/blitz-api-py/)
+[![CI](https://github.com/api-blitz/blitz-api-py/actions/workflows/ci.yml/badge.svg)](https://github.com/api-blitz/blitz-api-py/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/pypi/l/blitz-api-py.svg)](./LICENSE)
+
 The typed Python SDK for the [Blitz API](https://blitz-api.ai) — B2B data, search,
 and enrichment.
 
@@ -41,14 +46,35 @@ and enrichment.
 - **Resilient** — built-in client-side rate limiting, retries with backoff on
   `429`/`5xx`, and a typed exception hierarchy.
 - **Forward-compatible** — new fields the API adds never break deserialization.
+- **1:1 with the API** — request filters and response fields are snake_case,
+  matching [docs.blitz-api.ai](https://docs.blitz-api.ai).
 
 > Create and manage API keys at [app.blitz-api.ai](https://app.blitz-api.ai).
 
+> **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
+> loop streams every match up to the server-side limit (people: 50k results), which can be
+> a lot of credits. Bound spend with **`max_items`** (a client-side total cap on
+> `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
+> [Pagination](#pagination).
+
+## Contents
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Example: find, enrich, collect](#example-find-enrich-collect)
+- [Authentication](#authentication)
+- [Endpoints](#endpoints)
+- [Pagination](#pagination)
+- [Configuration](#configuration)
+- [Error handling](#error-handling)
+- [Forward compatibility](#forward-compatibility)
+- [Development](#development)
+
 ## Installation
 
 ```bash
 pip install blitz-api-py
-# or: uv add blitz-api-py
+# or: poetry add blitz-api-py   /   uv add blitz-api-py
 ```
 
 Requires Python 3.10+.
@@ -98,6 +124,61 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Example: find, enrich, collect
+
+A complete flow — find people, enrich each one's verified work email, collect the
+contacts. `max_items` caps the total fetched so the run can't surprise you with credits.
+
+```python
+from blitz_api import BlitzAPI
+from blitz_api.types import Industry, JobLevel
+
+client = BlitzAPI()  # reads BLITZ_API_KEY
+
+# 1. Find up to 25 VPs at software companies (typed filters, 1:1 with the API).
+leads = client.search.people(
+    company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
+    people={"job_level": [JobLevel.VP]},
+    max_results=25,
+).collect(max_items=25)  # client-side total cap — bounds credit spend
+
+# 2. Enrich each lead's verified work email from their LinkedIn profile URL.
+contacts: list[dict[str, str | None]] = []
+for person in leads:
+    if not person.linkedin_url:
+        continue
+    result = client.enrichment.email(person_linkedin_url=person.linkedin_url)
+    if result.found:
+        contacts.append({"name": person.full_name, "email": result.email})
+
+print(f"Collected {len(contacts)} contacts")
+```
+
+What comes back is typed and snake_case. A `Person` from the search above (fields are a
+**superset** — only what the profile has is populated, and unknown fields the API adds
+later are preserved):
+
+```python
+Person(
+    full_name="Jordan Lee",
+    headline="VP of Engineering at Acme",
+    linkedin_url="https://www.linkedin.com/in/example-person",
+    location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
+    experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
+    # first_name, last_name, skills, education, certifications, … also present
+)
+```
+
+And `enrichment.email(...)` returns:
+
+```python
+EmailEnrichmentResponse(
+    found=True,
+    email="jordan@acme.com",
+    all_emails=[EmailMatch(email="jordan@acme.com", email_domain="acme.com")],
+)
+```
+
 ## Authentication
 
 Pass the key explicitly or via the `BLITZ_API_KEY` environment variable:
@@ -119,7 +200,7 @@ All methods are grouped into four namespaces:
 | `client.account` | `key_info()` |
 | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
 | `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()` |
-| `client.utils` | `current_date()`, `company_employment_distribution()` |
+| `client.utils` | `current_date()`, `company_employment_distribution()`, `company_department_distribution()` |
 
 Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
 filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
@@ -131,6 +212,13 @@ The search methods return an **auto-paginating page**: iterate it and the SDK fe
 each subsequent page for you. `search.people`/`search.companies` are cursor-based;
 `search.employee_finder` is page-based — both behave identically here.
 
+> **`max_results` is the page size, not a total.** It's results per page, and the API
+> **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
+> loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
+> employee finder: 10k), which can be a lot of credits. Bound it with **`max_items`** on
+> `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
+> `break` out of the loop, or drive pages manually.
+
 ```python
 # Iterate every matching person across all pages — no cursor handling needed.
 for person in client.search.people(people={"job_level": ["VP"]}):
@@ -170,10 +258,13 @@ client = BlitzAPI(
 ```
 
 The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
-in any rolling second — so a single client instance stays under the API's limit (5 req/s
-by default; check your key's limit via
-`client.account.key_info().max_requests_per_seconds`). Across multiple processes you may
-still hit `429` — the retry path handles that.
+in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
+`.phone`) is throttled independently, mirroring the API's own limit, which is also per
+endpoint (5 req/s by default; check yours via
+`client.account.key_info().max_requests_per_seconds`). A single client instance therefore
+stays under the limit on every endpoint, so a burst on one never blocks another. Across
+multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
+path handles that.
 
 Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
 endpoint needs longer than the client default:
@@ -210,6 +301,12 @@ except BlitzError:
 but a **read timeout is not** — the server may already have processed (and billed) the
 request, so it surfaces as `APITimeoutError` rather than risking a double charge.
 
+## Forward compatibility
+
+Response models subclass a base configured with `extra="allow"`, so a field the API adds
+before this SDK models it is still present on the parsed object (via attribute access or
+`.model_extra`). Known fields stay precisely typed.
+
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the test/type/lint

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/README.md

@@ -1,5 +1,10 @@
 # blitz-api-py
 
+[![PyPI version](https://img.shields.io/pypi/v/blitz-api-py.svg)](https://pypi.org/project/blitz-api-py/)
+[![types: py.typed](https://img.shields.io/badge/types-py.typed-blue.svg)](https://pypi.org/project/blitz-api-py/)
+[![CI](https://github.com/api-blitz/blitz-api-py/actions/workflows/ci.yml/badge.svg)](https://github.com/api-blitz/blitz-api-py/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/pypi/l/blitz-api-py.svg)](./LICENSE)
+
 The typed Python SDK for the [Blitz API](https://blitz-api.ai) — B2B data, search,
 and enrichment.
 
@@ -10,14 +15,35 @@ and enrichment.
 - **Resilient** — built-in client-side rate limiting, retries with backoff on
   `429`/`5xx`, and a typed exception hierarchy.
 - **Forward-compatible** — new fields the API adds never break deserialization.
+- **1:1 with the API** — request filters and response fields are snake_case,
+  matching [docs.blitz-api.ai](https://docs.blitz-api.ai).
 
 > Create and manage API keys at [app.blitz-api.ai](https://app.blitz-api.ai).
 
+> **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
+> loop streams every match up to the server-side limit (people: 50k results), which can be
+> a lot of credits. Bound spend with **`max_items`** (a client-side total cap on
+> `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
+> [Pagination](#pagination).
+
+## Contents
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Example: find, enrich, collect](#example-find-enrich-collect)
+- [Authentication](#authentication)
+- [Endpoints](#endpoints)
+- [Pagination](#pagination)
+- [Configuration](#configuration)
+- [Error handling](#error-handling)
+- [Forward compatibility](#forward-compatibility)
+- [Development](#development)
+
 ## Installation
 
 ```bash
 pip install blitz-api-py
-# or: uv add blitz-api-py
+# or: poetry add blitz-api-py   /   uv add blitz-api-py
 ```
 
 Requires Python 3.10+.
@@ -67,6 +93,61 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Example: find, enrich, collect
+
+A complete flow — find people, enrich each one's verified work email, collect the
+contacts. `max_items` caps the total fetched so the run can't surprise you with credits.
+
+```python
+from blitz_api import BlitzAPI
+from blitz_api.types import Industry, JobLevel
+
+client = BlitzAPI()  # reads BLITZ_API_KEY
+
+# 1. Find up to 25 VPs at software companies (typed filters, 1:1 with the API).
+leads = client.search.people(
+    company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
+    people={"job_level": [JobLevel.VP]},
+    max_results=25,
+).collect(max_items=25)  # client-side total cap — bounds credit spend
+
+# 2. Enrich each lead's verified work email from their LinkedIn profile URL.
+contacts: list[dict[str, str | None]] = []
+for person in leads:
+    if not person.linkedin_url:
+        continue
+    result = client.enrichment.email(person_linkedin_url=person.linkedin_url)
+    if result.found:
+        contacts.append({"name": person.full_name, "email": result.email})
+
+print(f"Collected {len(contacts)} contacts")
+```
+
+What comes back is typed and snake_case. A `Person` from the search above (fields are a
+**superset** — only what the profile has is populated, and unknown fields the API adds
+later are preserved):
+
+```python
+Person(
+    full_name="Jordan Lee",
+    headline="VP of Engineering at Acme",
+    linkedin_url="https://www.linkedin.com/in/example-person",
+    location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
+    experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
+    # first_name, last_name, skills, education, certifications, … also present
+)
+```
+
+And `enrichment.email(...)` returns:
+
+```python
+EmailEnrichmentResponse(
+    found=True,
+    email="jordan@acme.com",
+    all_emails=[EmailMatch(email="jordan@acme.com", email_domain="acme.com")],
+)
+```
+
 ## Authentication
 
 Pass the key explicitly or via the `BLITZ_API_KEY` environment variable:
@@ -88,7 +169,7 @@ All methods are grouped into four namespaces:
 | `client.account` | `key_info()` |
 | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
 | `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()` |
-| `client.utils` | `current_date()`, `company_employment_distribution()` |
+| `client.utils` | `current_date()`, `company_employment_distribution()`, `company_department_distribution()` |
 
 Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
 filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
@@ -100,6 +181,13 @@ The search methods return an **auto-paginating page**: iterate it and the SDK fe
 each subsequent page for you. `search.people`/`search.companies` are cursor-based;
 `search.employee_finder` is page-based — both behave identically here.
 
+> **`max_results` is the page size, not a total.** It's results per page, and the API
+> **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
+> loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
+> employee finder: 10k), which can be a lot of credits. Bound it with **`max_items`** on
+> `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
+> `break` out of the loop, or drive pages manually.
+
 ```python
 # Iterate every matching person across all pages — no cursor handling needed.
 for person in client.search.people(people={"job_level": ["VP"]}):
@@ -139,10 +227,13 @@ client = BlitzAPI(
 ```
 
 The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
-in any rolling second — so a single client instance stays under the API's limit (5 req/s
-by default; check your key's limit via
-`client.account.key_info().max_requests_per_seconds`). Across multiple processes you may
-still hit `429` — the retry path handles that.
+in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
+`.phone`) is throttled independently, mirroring the API's own limit, which is also per
+endpoint (5 req/s by default; check yours via
+`client.account.key_info().max_requests_per_seconds`). A single client instance therefore
+stays under the limit on every endpoint, so a burst on one never blocks another. Across
+multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
+path handles that.
 
 Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
 endpoint needs longer than the client default:
@@ -179,6 +270,12 @@ except BlitzError:
 but a **read timeout is not** — the server may already have processed (and billed) the
 request, so it surfaces as `APITimeoutError` rather than risking a double charge.
 
+## Forward compatibility
+
+Response models subclass a base configured with `extra="allow"`, so a field the API adds
+before this SDK models it is still present on the parsed object (via attribute access or
+`.model_extra`). Known fields stay precisely typed.
+
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the test/type/lint

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/src/blitz_api/_client_async.py

@@ -50,13 +50,34 @@ class AsyncBlitzAPI(BaseClient):
             )
         self._http_client = http_client or httpx.AsyncClient(timeout=timeout)
         self._owns_http_client = http_client is None
-        self._rate_limiter = AsyncRateLimiter(rate_limit_rps)
+        self._rate_limit_rps = rate_limit_rps
+        # One limiter per endpoint path so each endpoint's rate limit is tracked
+        # independently (e.g. ``.email`` and ``.phone`` do not share a budget). Built
+        # lazily in ``_limiter_for`` on first use of each path.
+        self._rate_limiters: dict[str, AsyncRateLimiter] = {}
         if sleep is None:
             import asyncio
 
             sleep = asyncio.sleep
         self._sleep = sleep
 
+    def _limiter_for(self, path: str) -> AsyncRateLimiter:
+        """Return the per-endpoint limiter for ``path``, creating it on first use.
+
+        Each endpoint path gets its own sliding window so its rate limit is tracked
+        independently of every other endpoint.
+        """
+        limiter = self._rate_limiters.get(path)
+        if limiter is None:
+            # ``setdefault`` keeps concurrent first-callers on the same instance; any
+            # extra limiter built in a race is harmlessly discarded. Thread the client's
+            # ``sleep`` through so a custom/fake sleep injected for tests also drives the
+            # limiter's throttle wait, not just the retry backoff.
+            limiter = self._rate_limiters.setdefault(
+                path, AsyncRateLimiter(self._rate_limit_rps, sleep=self._sleep)
+            )
+        return limiter
+
     async def _request(
         self,
         method: str,
@@ -72,7 +93,7 @@ class AsyncBlitzAPI(BaseClient):
 
         attempt = 0
         while True:
-            await self._rate_limiter.acquire()
+            await self._limiter_for(path).acquire()
             try:
                 if timeout is None:
                     response = await self._http_client.request(

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/src/blitz_api/_client_sync.py

@@ -52,13 +52,34 @@ class BlitzAPI(BaseClient):
             )
         self._http_client = http_client or httpx.Client(timeout=timeout)
         self._owns_http_client = http_client is None
-        self._rate_limiter = RateLimiter(rate_limit_rps)
+        self._rate_limit_rps = rate_limit_rps
+        # One limiter per endpoint path so each endpoint's rate limit is tracked
+        # independently (e.g. ``.email`` and ``.phone`` do not share a budget). Built
+        # lazily in ``_limiter_for`` on first use of each path.
+        self._rate_limiters: dict[str, RateLimiter] = {}
         if sleep is None:
             import time
 
             sleep = time.sleep
         self._sleep = sleep
 
+    def _limiter_for(self, path: str) -> RateLimiter:
+        """Return the per-endpoint limiter for ``path``, creating it on first use.
+
+        Each endpoint path gets its own sliding window so its rate limit is tracked
+        independently of every other endpoint.
+        """
+        limiter = self._rate_limiters.get(path)
+        if limiter is None:
+            # ``setdefault`` keeps concurrent first-callers on the same instance; any
+            # extra limiter built in a race is harmlessly discarded. Thread the client's
+            # ``sleep`` through so a custom/fake sleep injected for tests also drives the
+            # limiter's throttle wait, not just the retry backoff.
+            limiter = self._rate_limiters.setdefault(
+                path, RateLimiter(self._rate_limit_rps, sleep=self._sleep)
+            )
+        return limiter
+
     def _request(
         self,
         method: str,
@@ -74,7 +95,7 @@ class BlitzAPI(BaseClient):
 
         attempt = 0
         while True:
-            self._rate_limiter.acquire()
+            self._limiter_for(path).acquire()
             try:
                 if timeout is None:
                     response = self._http_client.request(

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/src/blitz_api/_rate_limit_async.py

@@ -1,9 +1,11 @@
 """Client-side sliding-window rate limiter (async source; sync twin generated).
 
-The API enforces a per-key request rate (5 req/s by default). This limiter throttles
-outgoing requests *before* they are sent so a single client instance stays under the
-limit proactively; the server-side 429 retry path is the backstop for bursts across
-processes.
+The API enforces a per-endpoint request rate (5 req/s by default). This limiter throttles
+outgoing requests *before* they are sent. The client holds one limiter **per endpoint
+path** (see ``_client_async.py``), so each endpoint is throttled to ``rps`` independently,
+mirroring the server's per-endpoint budget; a single client instance therefore stays under
+the limit on every endpoint on its own. The server-side 429 retry path is the backstop for
+bursts across processes, which share the same per-endpoint budget.
 
 The algorithm is a sliding window: at most ``rps`` requests may begin in any rolling
 one-second window. This matches the Blitz docs ("max 5 requests per 1000 ms") and the

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/src/blitz_api/_rate_limit_sync.py

@@ -2,10 +2,12 @@
 # Do not edit by hand — edit the async source and run `python scripts/gen_sync.py`.
 """Client-side sliding-window rate limiter (async source; sync twin generated).
 
-The API enforces a per-key request rate (5 req/s by default). This limiter throttles
-outgoing requests *before* they are sent so a single client instance stays under the
-limit proactively; the server-side 429 retry path is the backstop for bursts across
-processes.
+The API enforces a per-endpoint request rate (5 req/s by default). This limiter throttles
+outgoing requests *before* they are sent. The client holds one limiter **per endpoint
+path** (see ``_client_async.py``), so each endpoint is throttled to ``rps`` independently,
+mirroring the server's per-endpoint budget; a single client instance therefore stays under
+the limit on every endpoint on its own. The server-side 429 retry path is the backstop for
+bursts across processes, which share the same per-endpoint budget.
 
 The algorithm is a sliding window: at most ``rps`` requests may begin in any rolling
 one-second window. This matches the Blitz docs ("max 5 requests per 1000 ms") and the

blitz_api_py-0.5.0/src/blitz_api/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"  # x-release-please-version

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/src/blitz_api/resources/_async/utils.py

@@ -5,13 +5,18 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from ..._compat import TimeoutParam
-from ...types.utils import CompanyEmploymentDistributionResponse, CurrentDateResponse
+from ...types.utils import (
+    CompanyDepartmentDistributionResponse,
+    CompanyEmploymentDistributionResponse,
+    CurrentDateResponse,
+)
 
 if TYPE_CHECKING:
     from ..._client import AsyncBlitzAPI
 
 _CURRENT_DATE = "/v2/utils/current-date"
 _EMPLOYMENT_DISTRIBUTION = "/v2/utils/company-employment-distribution"
+_DEPARTMENT_DISTRIBUTION = "/v2/utils/company-department-distribution"
 
 
 class AsyncUtilsResource:
@@ -41,3 +46,18 @@ class AsyncUtilsResource:
             cast_to=CompanyEmploymentDistributionResponse,
             timeout=timeout,
         )
+
+    async def company_department_distribution(
+        self, *, company_linkedin_url: str, timeout: TimeoutParam = None
+    ) -> CompanyDepartmentDistributionResponse:
+        """Get a company's employee count broken down by department.
+
+        Employees with no classified department are counted under ``"Other"``.
+        """
+        return await self._client._request(
+            "POST",
+            _DEPARTMENT_DISTRIBUTION,
+            body={"company_linkedin_url": company_linkedin_url},
+            cast_to=CompanyDepartmentDistributionResponse,
+            timeout=timeout,
+        )

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/src/blitz_api/resources/_sync/utils.py

@@ -7,13 +7,18 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from ..._compat import TimeoutParam
-from ...types.utils import CompanyEmploymentDistributionResponse, CurrentDateResponse
+from ...types.utils import (
+    CompanyDepartmentDistributionResponse,
+    CompanyEmploymentDistributionResponse,
+    CurrentDateResponse,
+)
 
 if TYPE_CHECKING:
     from ..._client import BlitzAPI
 
 _CURRENT_DATE = "/v2/utils/current-date"
 _EMPLOYMENT_DISTRIBUTION = "/v2/utils/company-employment-distribution"
+_DEPARTMENT_DISTRIBUTION = "/v2/utils/company-department-distribution"
 
 
 class UtilsResource:
@@ -43,3 +48,18 @@ class UtilsResource:
             cast_to=CompanyEmploymentDistributionResponse,
             timeout=timeout,
         )
+
+    def company_department_distribution(
+        self, *, company_linkedin_url: str, timeout: TimeoutParam = None
+    ) -> CompanyDepartmentDistributionResponse:
+        """Get a company's employee count broken down by department.
+
+        Employees with no classified department are counted under ``"Other"``.
+        """
+        return self._client._request(
+            "POST",
+            _DEPARTMENT_DISTRIBUTION,
+            body={"company_linkedin_url": company_linkedin_url},
+            cast_to=CompanyDepartmentDistributionResponse,
+            timeout=timeout,
+        )

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/src/blitz_api/types/__init__.py

@@ -53,8 +53,10 @@ from .shared import (
     Person,
 )
 from .utils import (
+    CompanyDepartmentDistributionResponse,
     CompanyEmploymentDistributionResponse,
     CurrentDateResponse,
+    DepartmentDistributionItem,
     EmploymentDistributionItem,
 )
 
@@ -105,4 +107,6 @@ __all__ = [
     "CurrentDateResponse",
     "EmploymentDistributionItem",
     "CompanyEmploymentDistributionResponse",
+    "DepartmentDistributionItem",
+    "CompanyDepartmentDistributionResponse",
 ]

{blitz_api_py-0.3.0 → blitz_api_py-0.5.0}/src/blitz_api/types/utils.py

@@ -8,6 +8,8 @@ __all__ = [
     "CurrentDateResponse",
     "EmploymentDistributionItem",
     "CompanyEmploymentDistributionResponse",
+    "DepartmentDistributionItem",
+    "CompanyDepartmentDistributionResponse",
 ]
 
 
@@ -33,3 +35,21 @@ class CompanyEmploymentDistributionResponse(BlitzModel):
     company_linkedin_url: str | None = None
     total_employees: int | None = None
     distribution: list[EmploymentDistributionItem] = []
+
+
+class DepartmentDistributionItem(BlitzModel):
+    """Employee count for a single department (Blitz job function).
+
+    Employees with no classified department are counted under ``"Other"``.
+    """
+
+    department: str | None = None
+    count: int | None = None
+
+
+class CompanyDepartmentDistributionResponse(BlitzModel):
+    """Result of ``utils.company_department_distribution``."""
+
+    company_linkedin_url: str | None = None
+    total_employees: int | None = None
+    distribution: list[DepartmentDistributionItem] = []

blitz_api_py-0.3.0/src/blitz_api/_version.py

@@ -1 +0,0 @@
-__version__ = "0.3.0"  # x-release-please-version