Getting started overview

The Covid-19 India API provides public access to granular COVID-19 data across India, disaggregated by state and district. This guide outlines the process for making a first request to the API, which does not require an account, API keys, or any form of authentication. The API is designed for ease of access, making it suitable for researchers, developers, and journalists who need to integrate up-to-date pandemic statistics. Data is available in JSON format, facilitating straightforward parsing and integration into various applications and analyses.

To ensure a smooth onboarding experience, this document details the steps from initial access to a successful data retrieval, along with common next steps and troubleshooting tips. The API's open nature aligns with principles of public health transparency, providing a resource for understanding the pandemic's progression within India. For a comprehensive overview of the available endpoints and data schema, refer to the official Covid-19 India API documentation.

Quick reference table

Step What to do Where
1. Review Documentation Understand data structure and endpoints. Covid-19 India API documentation
2. No Account Needed Authentication is not required. N/A
3. Construct Request URL Formulate the specific endpoint URL. Covid-19 India API endpoints
4. Make First Call Use a browser or HTTP client to retrieve data. Any web browser or HTTP client (e.g., cURL, Postman)
5. Parse JSON Response Process the retrieved data. Your application's code

Create an account and get keys

The Covid-19 India API is a public service and does not require users to create an account or obtain API keys for access. All data endpoints are openly available via standard HTTP GET requests. This design choice simplifies the process of data retrieval, removing common barriers to entry such as registration, authentication flows, and credential management. Developers can proceed directly to making requests without any preliminary setup related to accounts or keys.

This approach contrasts with many commercial APIs, which often implement OAuth 2.0 authorization or API key authentication to manage access, rate limits, and provide analytics. The Covid-19 India API's model prioritizes immediate and unhindered access to public health data, aligning with its mission to provide transparent information during the pandemic. Users should refer to the Covid-19 India API documentation for specific endpoint URLs and data structures, as no credential information will be provided.

Your first request

Making your first request to the Covid-19 India API is a direct process, as no authentication is required. You can use any HTTP client, web browser, or command-line tool like cURL to retrieve data. This example demonstrates how to fetch the daily status data for all states and districts.

Example 1: Fetch daily status data

The /v4/min/timeseries.min.json endpoint provides a daily summary of COVID-19 cases, recoveries, and deaths across India. This is a common starting point for understanding overall trends.

Request URL:

GET https://api.covid19india.org/v4/min/timeseries.min.json

Using a web browser:

Simply paste the URL https://api.covid19india.org/v4/min/timeseries.min.json into your browser's address bar and press Enter. The browser will display the raw JSON data.

Using cURL (command line):

curl https://api.covid19india.org/v4/min/timeseries.min.json

Expected (truncated) JSON response:

{
  "AN": {
    "dates": {
      "2020-03-26": {
        "delta": {
          "confirmed": 1
        },
        "total": {
          "confirmed": 1
        }
      },
      "2020-03-27": {
        "delta": {
          "confirmed": 5
        },
        "total": {
          "confirmed": 6
        }
      }
    }
  },
  "AP": {
    "dates": {
      "2020-03-12": {
        "delta": {
          "confirmed": 1
        },
        "total": {
          "confirmed": 1
        }
      },
      "2020-03-20": {
        "delta": {
          "confirmed": 2
        },
        "total": {
          "confirmed": 3
        }
      }
    }
  }
  // ... more states and dates ...
}

This response structure provides an object where keys represent state codes (e.g., "AN" for Andaman and Nicobar Islands, "AP" for Andhra Pradesh). Each state object contains a "dates" object, with keys representing dates in YYYY-MM-DD format. Within each date, "delta" shows daily changes, and "total" shows cumulative figures for confirmed cases, recoveries, and deaths.

Example 2: Fetch state-wise data

To get a snapshot of current or recent state-wise data, you can use the /v4/min/data.min.json endpoint.

Request URL:

GET https://api.covid19india.org/v4/min/data.min.json

Using a web browser:

Navigate to https://api.covid19india.org/v4/min/data.min.json in your browser.

Using cURL (command line):

curl https://api.covid19india.org/v4/min/data.min.json

Expected (truncated) JSON response:

{
  "AN": {
    "delta": {
      "confirmed": 0,
      "recovered": 0
    },
    "delta21_14": {
      "confirmed": 0,
      "recovered": 0
    },
    "districts": {
      "Nicobars": {
        "total": {
          "confirmed": 0
        }
      }
    },
    "meta": {
      "date": "2021-10-18",
      "last_updated": "2021-10-19T06:01:21+05:30",
      "population": 397000
    },
    "total": {
      "confirmed": 7652,
      "deceased": 129,
      "recovered": 7523,
      "tested": 681026,
      "vaccinated1": 305545,
      "vaccinated2": 217684
    }
  },
  "AP": {
    "delta": {
      "confirmed": 31,
      "recovered": 108
    },
    "delta21_14": {
      "confirmed": 419,
      "recovered": 777
    },
    "districts": {
      "Anantapur": {
        "total": {
          "confirmed": 158226
        }
      }
    },
    "meta": {
      "date": "2021-10-18",
      "last_updated": "2021-10-19T06:01:21+05:30",
      "population": 53400000
    },
    "total": {
      "confirmed": 2065870,
      "deceased": 14416,
      "recovered": 2049961,
      "tested": 30348700,
      "vaccinated1": 32669469,
      "vaccinated2": 19570180
    }
  }
  // ... more states ...
}

This endpoint provides more detailed information including current delta values, cumulative totals, district-level breakdowns, and metadata such as population and last update time for each state.

Common next steps

After successfully retrieving data from the Covid-19 India API, developers typically proceed with several common steps to integrate and utilize the information:

  1. Data Parsing and Storage: The API returns data in JSON format. Your application will need to parse this data. For persistent use, consider storing relevant data in a local database or cache to reduce the frequency of API calls and improve application performance. Tools like MongoDB's flexible document model or a relational database can be used, depending on the scale and structure of your application.

  2. Data Visualization: Many users integrate this data into dashboards or visual analytics tools. Libraries such as D3.js, Chart.js, or plotly.js can be used to create interactive charts and graphs illustrating trends in confirmed cases, recoveries, and deaths. Geographic information systems (GIS) platforms, such as those provided by ArcGIS Developers, can map district-level data to visualize spatial distribution.

  3. Application Development: Build applications that consume and display the data. This could range from simple web pages to complex analytical tools. Consider developing features like historical trend analysis, comparisons between states, or predictive modeling based on the provided time-series data.

  4. Error Handling and Robustness: Implement proper error handling to manage potential network issues or unexpected API responses. Although the Covid-19 India API is generally stable, robust applications should anticipate and gracefully handle scenarios where data might be unavailable or malformed.

  5. Monitoring and Updates: Since public health data is dynamic, plan to periodically fetch updates from the API. Implement a schedule for data synchronization to ensure your application always displays the most current information. Be mindful of the API's update frequency, as documented on the official API page.

  6. Community Engagement: The Covid-19 India project is community-driven. Engaging with the community can provide insights into data nuances, new features, or potential issues. Check for any community forums or GitHub repositories associated with the project for discussions and contributions.

Troubleshooting the first call

While the Covid-19 India API is designed for simplicity, you might encounter issues during your first request. Here are common problems and their solutions:

  • 404 Not Found:

    • Issue: The requested resource could not be found.
    • Solution: Double-check the URL for typos. Ensure you are using the exact endpoint paths as specified in the Covid-19 India API documentation. For example, verify that /v4/min/timeseries.min.json is correctly typed.

  • Network Connection Issues:

    • Issue: Your client cannot reach the API server.
    • Solution: Verify your internet connection. Try accessing other websites to confirm connectivity. If you are behind a corporate firewall, ensure that requests to api.covid19india.org are not blocked.

  • JSON Parsing Errors:

    • Issue: Your application fails to parse the JSON response.
    • Solution: Use a JSON validator (many online tools are available) to inspect the API response. This can help identify malformed JSON, though unlikely with this API. Ensure your parsing library or code is correctly handling the JSON structure, especially nested objects and arrays.

  • Empty or Unexpected Data:

    • Issue: The API returns an empty response or data that doesn't match expectations.
    • Solution: Check the specific endpoint documentation to understand the expected data format and any potential query parameters (though this API is generally simple and parameter-free for its main endpoints). Data updates occur periodically; an empty response might indicate a temporary data availability issue or a specific date without recorded events.

  • Rate Limiting (Unlikely for this API):

    • Issue: Although the Covid-19 India API does not officially state rate limits, excessive requests in a short period could theoretically lead to temporary blocking by network infrastructure.
    • Solution: If you are making a very high volume of requests, consider spacing them out or implementing a caching layer for frequently accessed data to reduce direct API calls.

  • Browser-Specific Issues (CORS):

    • Issue: When accessing the API from client-side JavaScript in a web browser, you might encounter Cross-Origin Resource Sharing (CORS) errors.
    • Solution: The Covid-19 India API generally supports CORS for widespread access. If you encounter a CORS error, ensure your browser and web server configurations are not overly restrictive. For development, browser extensions can sometimes temporarily disable CORS, but a proper solution involves the server sending appropriate CORS headers.