# ICA - Conference API Documentation

## Overview

The ICA Conference API allows developers to search and retrieve information about academic conferences worldwide. This API is designed to be used with ChatGPT custom actions or any application that needs conference data.

**Base URL:** `https://academicworldresearch.org/api/gpt`

---

## Authentication

All API requests require an API key passed in the header:

```
X-API-Key: your_api_key_here
```

To obtain an API key, contact the ICA team.

---

## Rate Limits

| Plan | Requests/Minute | Requests/Day |
|------|-----------------|--------------|
| Free | 60 | 1,000 |
| Pro | 300 | 50,000 |

---

## Endpoints

### 1. Search Conferences

```
GET /api/gpt/conferences
```

Search for conferences with various filters.

#### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | Free-text search (searches event name, topic, sub-topic) |
| `topic` | string | No | Filter by main topic (e.g., "Engineering", "Business") |
| `subtopic` | string | No | Filter by sub-topic (e.g., "Aerospace", "Marketing") |
| `country` | string | No | Filter by single country |
| `countries` | string | No | Filter by multiple countries (comma-separated) |
| `continent` | string | No | Filter by continent: Asia, Europe, North America, South America, Africa, Oceania |
| `city` | string | No | Filter by city name |
| `type` | string | No | Event type: conference, seminar, workshop, webinar |
| `from` | date | No | Events starting from this date (YYYY-MM-DD) |
| `to` | date | No | Events ending before this date (YYYY-MM-DD) |
| `month` | string | No | Filter by month (YYYY-MM format, e.g., 2026-03) |
| `year` | number | No | Filter by year (e.g., 2026) |
| `limit` | number | No | Max results (1-50, default: 10) |
| `offset` | number | No | Pagination offset (default: 0) |

#### Example Request

```bash
curl -X GET "https://academicworldresearch.org/api/gpt/conferences?q=machine%20learning&continent=Asia&month=2026-03&limit=10" \
  -H "X-API-Key: your_api_key"
```

#### Example Response

```json
{
  "success": true,
  "query": {
    "q": "machine learning",
    "continent": "Asia",
    "month": "2026-03"
  },
  "filters_applied": {
    "search_terms": ["machine", "learning"],
    "countries_included": ["India", "China", "Japan", "Singapore", "...25 more"],
    "date_range": {
      "from": "2026-03-01",
      "to": "2026-03-31"
    }
  },
  "total": 127,
  "showing": 10,
  "conferences": [
    {
      "id": 123456,
      "name": "International Conference on Machine Learning and AI",
      "type": "Conference",
      "topic": "Engineering",
      "sub_topic": "Artificial Intelligence",
      "dates": {
        "start": "2026-03-15",
        "end": "2026-03-17",
        "formatted": "Mar 15-17, 2026"
      },
      "location": {
        "city": "Singapore",
        "country": "Singapore",
        "venue": "Marina Bay Sands Convention Centre"
      },
      "organizer": "IEEE",
      "website": "https://example.com/icml2026"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true,
    "next_offset": 10
  }
}
```

---

### 2. Get Single Conference

```
GET /api/gpt/conferences/{id}
```

Get detailed information about a specific conference.

#### Example Request

```bash
curl -X GET "https://academicworldresearch.org/api/gpt/conferences/123456" \
  -H "X-API-Key: your_api_key"
```

---

### 3. List Topics

```
GET /api/gpt/topics
```

Get all available conference topics.

#### Example Response

```json
{
  "success": true,
  "total": 15,
  "topics": [
    { "name": "Engineering", "count": 245000 },
    { "name": "Business And Economics", "count": 180000 },
    { "name": "Health and Medicine", "count": 156000 }
  ]
}
```

---

### 4. List Countries

```
GET /api/gpt/countries
```

Get all countries with conferences.

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `continent` | string | Filter by continent |

#### Example Request

```bash
curl -X GET "https://academicworldresearch.org/api/gpt/countries?continent=Europe" \
  -H "X-API-Key: your_api_key"
```

---

### 5. Get Statistics

```
GET /api/gpt/stats
```

Get overall statistics about the conference database.

#### Example Response

```json
{
  "success": true,
  "statistics": {
    "total_conferences": 970000,
    "total_countries": 195,
    "total_topics": 15,
    "upcoming_this_month": 8500,
    "date_range": {
      "earliest": "2024-01-01",
      "latest": "2027-12-31"
    }
  },
  "continents": [
    { "name": "Asia", "count": 320000 },
    { "name": "Europe", "count": 280000 }
  ]
}
```

---

## Search Combinations

The API supports flexible search combinations:

| User Query | API Parameters |
|------------|----------------|
| "AI conferences in India" | `?q=AI&country=India` |
| "Medical conferences in Europe March 2026" | `?topic=Health%20and%20Medicine&continent=Europe&month=2026-03` |
| "Engineering seminars in Sydney" | `?topic=Engineering&city=Sydney&type=seminar` |
| "Business conferences in Asia Q1 2026" | `?topic=Business&continent=Asia&from=2026-01-01&to=2026-03-31` |
| "Aerospace workshops in USA or Canada" | `?subtopic=Aerospace&countries=USA,Canada&type=workshop` |

---

## Continent Mapping

When using the `continent` parameter, the following countries are included:

### Asia
India, China, Japan, South Korea, Singapore, Malaysia, Thailand, Vietnam, Indonesia, Philippines, Taiwan, Hong Kong, UAE, Saudi Arabia, Qatar, Israel, Turkey, Pakistan, Bangladesh, Sri Lanka, Nepal, Myanmar, Cambodia, Laos, Mongolia, Kazakhstan, Uzbekistan, Iran, Iraq, Jordan, Lebanon, Kuwait, Bahrain, Oman

### Europe
United Kingdom, Germany, France, Italy, Spain, Netherlands, Belgium, Switzerland, Austria, Poland, Czech Republic, Portugal, Greece, Sweden, Norway, Denmark, Finland, Ireland, Hungary, Romania, Bulgaria, Croatia, Slovenia, Slovakia, Serbia, Ukraine, Russia, Estonia, Latvia, Lithuania, Luxembourg, Malta, Cyprus, Iceland

### North America
United States, Canada, Mexico

### South America
Brazil, Argentina, Chile, Colombia, Peru, Venezuela, Ecuador, Bolivia, Paraguay, Uruguay, Guyana, Suriname

### Africa
South Africa, Egypt, Nigeria, Kenya, Morocco, Tunisia, Ghana, Tanzania, Ethiopia, Uganda, Rwanda, Senegal, Ivory Coast, Cameroon, Algeria, Zimbabwe

### Oceania
Australia, New Zealand, Fiji, Papua New Guinea, Samoa, Tonga, Vanuatu

---

## Error Responses

### 400 Bad Request
```json
{
  "success": false,
  "error": "Invalid parameter",
  "message": "The 'limit' parameter must be between 1 and 50"
}
```

### 401 Unauthorized
```json
{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

### 404 Not Found
```json
{
  "success": false,
  "error": "Not found",
  "message": "Conference with ID 123456 not found"
}
```

### 429 Too Many Requests
```json
{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit. Please try again later."
}
```

### 500 Internal Server Error
```json
{
  "success": false,
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}
```

---

## ChatGPT Integration

To use this API with a custom ChatGPT:

1. **Create a Custom GPT** in ChatGPT
2. **Add an Action** with the OpenAPI schema
3. **Configure Authentication** with your API key
4. **Test** with natural language queries

### OpenAPI Schema URL
```
https://academicworldresearch.org/api/gpt/openapi
```

### Sample GPT Instructions
```
You are an academic conference assistant. When users ask about conferences:

1. Use the searchConferences action to find relevant events
2. Present results in a clear, organized format
3. Include dates, locations, and website links
4. Offer to filter by topic, location, or date if results are too broad
5. Use getConferenceDetails for more information about specific events
```

---

## Support

For API access, questions, or issues:
- Email: api@academicworldresearch.org
- Website: https://academicworldresearch.org/contact

---

**Version:** 1.0.0  
**Last Updated:** February 2026