Hirebase Python SDK

A Python client library for the Hirebase API. This SDK provides Python developers an easy way to integrate with Hirebase services for job search, company data, and product management.

Installation

pip install hirebase

or clone and install locally:

git clone https://github.com/HireBase-1/hirebase-sdk-python && cd hirebase-sdk-python
pip install -e .

Authentication

The SDK uses API Key authentication:

import hirebase

# Use environment variable (recommended)
# export HIREBASE_API_KEY=your_api_key
client = hirebase.create_client()

# Or initialize with API key
client = hirebase.create_client(api_key="your_api_key")

Access your API key using Hirebase in User Settings.

Usage Examples

Searching for Jobs

from hirebase import Hirebase, SearchJobsParams, Location

# Initialize the client
hirebase_client = Hirebase(api_key="your_api_key")

# Create search parameters
search_params = SearchJobsParams(
    job_titles=["Software Engineer", "Software Developer"],
    keywords=["Python", "Machine Learning"],
    location_types=["Remote", "Hybrid"],
    geo_locations=[
        Location(city="San Francisco", region="California", country="USA")
    ],
    experience=["Mid", "Senior"],
    salary=[100000, 150000],  # Min, Max
    include_no_salary=True,
    job_types=["Full-time"],
    visa=True,
    limit=10
)

# Estimate the search cost (for metered plans)
cost = hirebase_client.jobs.estimate_search_cost(search_params)
print(f"Estimated search cost: {cost.cost} units")

# Perform the search
results = hirebase_client.jobs.search_jobs(search_params)

# Display results
print(f"Found {results.total_count} jobs from {results.company_count} companies")
for job in results.jobs:
    print(f"{job.job_title} at {job.company_name}")
    if job.locations:
        locations = [f"{loc.city}, {loc.region}, {loc.country}" for loc in job.locations if loc.city]
        print(f"Locations: {', '.join(locations)}")
    if job.salary_range:
        print(f"Salary: {job.salary_range.min} - {job.salary_range.max} {job.salary_range.currency} per {job.salary_range.period}")

Vector Search for Jobs

# Semantic search using a text description
results = hirebase_client.jobs.vector_search(
    search_type="summary",
    query="Senior Python developer with experience in machine learning and cloud infrastructure",
    location_types=["Remote"],
    salary_min=120000,
    include_no_salary=True
)

# Resume-based search
results = hirebase_client.jobs.vector_search(
    search_type="resume",
    artifact_id="your_resume_id",
    top_k=100
)

# Search for jobs similar to another job
results = hirebase_client.jobs.vector_search(
    search_type="job",
    job_id="job_id_to_match"
)

# Display results with match scores
for job in results.jobs:
    print(f"{job.job_title} at {job.company_name} - Match Score: {job.match_score}")

Working with Companies

from hirebase import Hirebase, SearchCompaniesParams

# Initialize the client
hirebase_client = Hirebase(api_key="your_api_key")

# Search for companies
company_params = SearchCompaniesParams(
    industries=["Technology", "Software"],
    locations=["San Francisco"]
)
company_results = hirebase_client.companies.search_companies(company_params)

# Display company results
for company in company_results.companies:
    print(f"{company.company_name} - {company.total_jobs} jobs")
    if company.size_range:
        print(f"Size: {company.size_range.min}-{company.size_range.max} employees")

# Get details about a specific company
company = hirebase_client.companies.get_company_by_slug("example-corp")

# Get jobs for a specific company
company_jobs = hirebase_client.companies.get_company_jobs(
    company_slug="example-corp",
    sort_by="relevance",
    sort_order="desc"
)

# Get industry list
industries = hirebase_client.companies.get_industries()

Managing Products and API Usage

from hirebase import Hirebase, CheckoutRequest

# Initialize the client
hirebase_client = Hirebase(api_key="your_api_key")


# Get user's subscriptions
user_products = hirebase_client.products.get_user_products()

# Check if user has API access
has_api_access = hirebase_client.products.user_has_api_access()

# Get API tier (free, ultra, unlimited)
api_tier = hirebase_client.products.get_user_tier()
print(f"API Tier: {api_tier}")

# Get usage statistics
usage_data = hirebase_client.products.get_user_usage(time_period="week")

# Display API usage
if "API_SEARCH_ACCESS" in usage_data:
    for day_usage in usage_data["API_SEARCH_ACCESS"]:
        print(f"Date: {day_usage.date} - Used: {day_usage.usage_count} / Limit: {day_usage.daily_limit}")

Error Handling

The SDK uses custom exceptions to handle API errors:

from hirebase import (
    Hirebase, HirebaseError, AuthenticationError, RateLimitError
)

hirebase_client = Hirebase(api_key="your_api_key")

try:
    results = hirebase_client.jobs.search_jobs(search_params)
except AuthenticationError as e:
    print(f"Authentication error: {e}")
except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
    print(f"Reset time: {e.reset_time}")
except HirebaseError as e:
    print(f"API error: {e}")

Usage Limits

API requests are subject to usage/rate limits based on your subscription tier:

• Free tier: 3 pages per day
• Ultra tier: 1000 pages per day, then $0.20 per subsequent page
• Unlimited tier: No usage limits

See Hirebase User Settings for more information on the products that you have access too and your usage.

License

This SDK is distributed under the MIT License. See LICENSE file for more information.