# Jobs API Documentation

## Introduction

Welcome to the Jobs API, your gateway to real-time job postings aggregated from across the internet. This API provides developers with access to a wealth of job data, enabling the creation of job boards, career sites, or integration of job listings into existing applications.

## API Key

To use the Jobs API, you'll need an API key. You can get started for free:

- Subscribe for free at [indianapi.in/jobs-api](https://indianapi.in/jobs-api) to obtain your API key
- For higher usage limits, paid plans are available

## Base URL

```
https://jobs.indianapi.in
```

## Authentication

Include your API key in the header of each request:

```
X-Api-Key: YOUR_API_KEY_HERE
```

## API Sandbox

To test the API without using your request quota, use our sandbox environment:

[indianapi.in/sandbox/jobs-api](https://indianapi.in/sandbox/jobs-api)

---

## Endpoints

### 1. Fetch Jobs Data

Retrieve a list of job postings with detailed information.

- **Endpoint:** `GET /jobs`

**Parameters:**
- `limit` (optional, string): Number of job listings to return
- `location` (string): Filter jobs by location
- `title` (string): Search for jobs by title
- `company` (string): Filter jobs by company
- `experience` (string): Filter by required experience level
- `job_type` (string): Filter by job type (e.g., "Full Time", "Part Time")

**Example Request:**
```bash
curl --request GET \
  --url 'https://jobs.indianapi.in/jobs?limit=10' \
  --header 'X-Api-Key: YOUR_API_KEY_HERE'
```

**Example Response:**
```json
[
  {
    "id": 1,
    "title": "Software Engineer - Fresher",
    "company": "TechCorp",
    "about_company": "TechCorp is a leading software development company...",
    "job_description": "We are looking for enthusiastic software engineers to join our team...",
    "job_title": "Software Engineer",
    "job_type": "Full Time",
    "location": "Bangalore",
    "experience": "Fresher",
    "role_and_responsibility": "Develop and maintain software applications...",
    "education_and_skills": "B.Tech/B.E. in Computer Science or related field...",
    "apply_link": "https://techcorp.com/careers/software-engineer-fresher",
    "posted_date": "2024-09-27T02:15:00"
  }
]
```

---

## Response Structure

Each job listing in the response will contain the following fields:

| Field | Type | Description |
|---|---|---|
| `id` | integer | Unique identifier for the job posting |
| `title` | string | Full title of the job listing |
| `company` | string | Name of the company offering the job |
| `about_company` | string | Brief description of the company |
| `job_description` | string | Detailed description of the job |
| `job_title` | string | Specific title of the job role |
| `job_type` | string | Type of employment (e.g., "Full Time", "Part Time") |
| `location` | string | Location of the job |
| `experience` | string | Required experience level |
| `role_and_responsibility` | string | Detailed responsibilities of the role |
| `education_and_skills` | string | Required education and skills |
| `apply_link` | string | URL to apply for the job |
| `posted_date` | string | Date and time when the job was posted (ISO 8601 format) |

---

## Error Handling

| Status Code | Meaning |
|---|---|
| 200 | Successful request |
| 401 | Unauthorized (invalid or missing API key) |
| 422 | Validation error (check your parameters) |
| 500 | Internal server error |

---

## Rate Limiting

Free accounts receive a limited number of requests. For higher volumes, paid plans are available at [indianapi.in](https://indianapi.in/jobs-api).

---

## Best Practices

1. Always include the `limit` parameter to control the number of results returned.
2. Use appropriate filters to narrow down job searches and reduce unnecessary data transfer.
3. Cache responses when appropriate to reduce API calls and improve performance.
4. Handle errors gracefully in your application, providing meaningful feedback to users.
5. Keep your API key secure and never expose it in client-side code.
