Introduction to the Civil Litigation Search API

This guide is designed to help you seamlessly integrate our API into your applications, enabling you to query a vast database of civil litigation cases with ease.

Before diving into the specifics, it's important to address some prerequisites and key considerations:

API Authentication

The CNS Case Portal API requires authentication. To successfully make requests, you'll need to include a valid Bearer Token in the Authorization header of each request. If you're not familiar with the process of obtaining and using this token, please refer to our detailed authentication guide available at API Authentication Guide.

Please note that this guide does not cover the steps for inserting the Bearer Token in the Authorization header, but it is a mandatory step for all API requests.

Token Expiration

Be aware that the Bearer Token has a maximum validity of one hour. Therefore, it's crucial to implement appropriate logic in your code to handle token expiration and renewal. This aspect is outside the scope of this guide, but it is essential for maintaining uninterrupted API access.

Scope of This Guide

This guide provides an in-depth look at how to make queries to the API, handle and interpret the responses, and efficiently navigate through paginated results. Furthermore, we have included essential strategies to manage the API's throttling limit.

Please note, while we provide code examples, these are for illustrative purposes and may require adaptation to fit your specific application context. The examples are based on Node.js and Axios but can be translated into other programming languages and frameworks as needed.

Quick Overview

  • Making a Query: Learn how to construct and send a query to the API, including understanding the endpoint, request body, and query parameters.
  • Handling the Response: Discover how to interpret the JSON response from the API, including parsing through the metadata and individual case details.
  • Paging Through Results: Gain insights on how to paginate through large sets of results and handle the API's rate limits effectively.

With this guide, we aim to provide you with the tools and knowledge necessary to harness the full potential of the CNS Case Portal API.

Making a Query

Civil Litigation Search Endpoint

The API endpoint for searching legal cases is https://api.cnscaseportal.com/api/1/search/civil-litigation. This endpoint allows users to query a database of civil litigation cases based on specific parameters. Here's a breakdown of the query parameters:

  • Page: Specifies the page number of the search results. Useful for pagination.
  • PageSize: Determines the number of cases returned in a single response. The maximum value for PageSize is 100.
  • SortBy: This parameter allows sorting of the results based on specific case attributes, like FiledAt.
  • SortOrder: Determines the order of sorting, either ascending (asc) or descending (desc).
  • Options: A set of parameters for receiving back aggregate counts on available aggregated data points: Judge, NOS, Plaintiff Firms, and Defendant Firms (typically this is not used when using the API directly, further details will be provided in a future article)

Request Body

The request body for the API is in JSON format and includes several important fields:

  • requestData:
    • query: The search query string. It can include various filters and conditions to refine the search results. In the given example, the query retrieves cases created on a specific date (2024-03-05), excluding those with defendantLawyers or defendantLawyerFirms.
    • startDate and endDate: These fields define the date range for the search query based on the filing date of cases. Typically you would set this to a much larger range than any date restrictions provided in the query. They are represented in the ISO 8601 date format.
  • engine: Specifies the search engine to use, which in this case is "ES" (Elasticsearch).

Here's an example of how to structure your request body:

{
  "requestData": {
   "query": "createdAtUTC:[2022-01-01 TO 2024-01-01] AND def:Google",
   "startDate": "2022-01-01T00:00:00.000Z",
   "endDate": "2023-12-31T23:59:59.999Z"
  },
  "engine": "ES"
}

For a complete list of all available query fields, please refer to our Civil Litigation Search Commands article.

Code Example

The following Node.js example uses the axios library to send a POST request to the API. If you haven't already, you need to install axios using npm install axios.

const axios = require('axios');

const queryData = {
  requestData: {
    query: "createdAtUTC:[2022-01-01 TO 2024-01-01] AND def:Google",
    startDate: "2022-01-01T00:00:00.000Z",
    endDate: "2023-12-31T23:59:59.999Z"
  },
  engine: "ES"
};

axios.post('<https://api.cnscaseportal.com/api/1/search/civil-litigation?Page=1&PageSize=100&SortBy=FiledAt&SortOrder=desc&OptionsOnly=false>', queryData)
  .then(response => {
    console.log("Response data:", response.data);
  })
  .catch(error => {
    console.error('There was an error!', error);
  });

In this example, the query parameters are set to retrieve the first page of results, with a maximum of 100 cases per page, sorted by the date they were filed in descending order. Adjust these parameters as needed for your specific use case.

Handling the Response

After making a query to the API, the response you receive will be structured in JSON format. Understanding how to interpret and navigate this response is crucial for effectively utilizing the API. The response typically consists of metadata about the search result and the actual data pertaining to the legal cases.

Response Structure

The structure of the response is as follows:

  • meta: This section contains metadata about the response, which is crucial for understanding the context of the returned data.
    • currentPage: Indicates the current page number of the results.
    • pageSize: Shows the number of cases per page, as specified in your request.
    • totalCount: The total number of cases that match your query criteria.
    • took: The time taken to execute the query, usually in milliseconds.
    • fuzzinessDistance: Indicates the degree of fuzziness applied in the search, if any.
  • engine: The search engine used, as specified in your request (e.g., "ES" for Elasticsearch).
  • responseData: An array of objects, where each object represents a legal case that matches your query. Each object contains detailed information about a case, such as:
    • Case identifiers like id, litigationName, caseNumber.
    • Dates related to the case (filedAt, publishedAtUTC, etc.).
    • Information about the parties involved (plaintiffs, defendants).
    • Legal representatives (plaintiffLawyers, defendantLawyers).
    • Additional metadata such as summary, courtName, natureOfSuit.

Example Response Interpretation

Here's how you would interpret a typical response:

{
  "meta": {
    "currentPage": 1,
    "pageSize": 100,
    "totalCount": 1405,
    "took": 169,
    "fuzzinessDistance": 0
  },
  "engine": "ES",
  "responseData": [
    {
      "_score": null,
      "id": "3_1_3007_b120b017-df7a-499b-ae0d-d7737d02d96b",
      "litigationName": "Syreeta LaShawn McNeal, Esq. v. <mark>Google</mark> LLC, YouTube, LLC, TikTok Inc., et al.",
      "filedAt": "2023-12-29T00:00:00",
      // Other fields...
    }
  ]
}

In this example:

  • meta.currentPage is 1, indicating this is the first page of results.
  • meta.pageSize is 100, meaning each page contains 100 cases (as specified in your query).
  • meta.totalCount is 1405, showing the total number of cases matching your criteria.
  • The responseData array contains detailed information about each case, with various attributes like filedAt, the date the case was filed.

Navigating Through the Response

When navigating through the response:

  1. Check Pagination: Refer to meta.currentPage and meta.totalCount to understand where you are in the dataset and how many pages of data are available.
  2. Iterate Through Cases: Loop through the responseData array to process each case individually.
  3. Extract Necessary Information: Depending on your needs, extract and utilize relevant information from each case object, such as the litigationName, filedAt date, parties involved, and case summaries.

Handling Large Datasets

For large datasets (e.g., when meta.totalCount is high):

  • Be mindful of the pagination and iterate through pages as needed.
  • Ensure that you have implemented proper methods to handle any API throttling

Paging Through the Results with Throttling Management

When working with APIs, especially those with a large number of results and rate limits, it's crucial to implement efficient pagination and handle throttling effectively. The API you're working with is throttled to 10 requests per minute (higher limits are available at higher tiers) and responds with a 429 status code if this limit is exceeded. We'll outline a strategy to paginate through the results while respecting the API's throttling limits.

Understanding Pagination

Before diving into the logic, let's recap pagination:

  • Pagination: The process of dividing the API response into discrete pages.
  • currentPage and pageSize: Indicate the current page and the number of items per page, respectively.
  • totalCount: The total number of items that match the query.

Code Example with Throttling Handling

In this example, we'll use Node.js and Axios to paginate through the results. We'll also include logic to handle the API's rate limit.

  1. Setup: First, ensure you have Axios installed (npm install axios). Then, define your query data and initial parameters.
const axios = require('axios');
let currentPage = 1;
const pageSize = 100;  // Adjust based on your requirements
const maxRequestsPerMinute = 10;
let requestCount = 0;
let timeOfFirstRequest = Date.now();

const queryData = {
  requestData: {
    query: "createdAtUTC:[2022-01-01 TO 2024-01-01] AND def:Google",
    startDate: "2022-01-01T00:00:00.000Z",
    endDate: "2023-12-31T23:59:59.999Z"
  },
  engine: "ES"
};
  1. Pagination Function: Create a function to handle pagination and respect the rate limit.
async function fetchPage() {
  try {
    // Throttling check
    if (requestCount >= maxRequestsPerMinute) {
      let currentTime = Date.now();
      if (currentTime - timeOfFirstRequest < 60000) {
        // If less than a minute has passed, wait the remaining time
        const waitTime = 60000 - (currentTime - timeOfFirstRequest);
        console.log(`Rate limit reached. Waiting for ${waitTime / 1000} seconds.`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
      }
      // Reset counters
      requestCount = 0;
      timeOfFirstRequest = Date.now();
    }

    const response = await axios.post(`https://api.cnscaseportal.com/api/1/search/civil-litigation?Page=${currentPage}&PageSize=${pageSize}&SortBy=FiledAt&SortOrder=desc&OptionsOnly=false`, queryData);

    if (response.status === 200) {
      console.log(`Page ${currentPage} fetched`);
      // Process the data here

      currentPage++;
      requestCount++;
    }
  } catch (error) {
    if (error.response && error.response.status === 429) {
      // API throttling limit exceeded
      console.error('429 - Throttling limit exceeded. Waiting to retry...');
      await new Promise(resolve => setTimeout(resolve, error.response.data.timeLeft * 1000));
      // Retry the same page
      await fetchPage();
    } else {
      console.error('An error occurred:', error.message);
    }
  }
}

async function fetchAllPages() {
  const totalPages = Math.ceil(1405 / pageSize);  // Total count / pageSize
  for (let i = 0; i < totalPages; i++) {
    await fetchPage();
  }
}

fetchAllPages();

In this logic:

  • We keep track of the number of requests made within a minute (requestCount).
  • If we hit the rate limit, we calculate the time to wait before making the next request (waitTime).
  • In case of a 429 error, we use the timeLeft field from the response to wait for the appropriate duration before retrying.

Key Points to Remember

  • Handle 429 Status Code: When you encounter a 429 response, use the timeLeft value from the API response to wait before sending the next request.
  • Respect Rate Limits: Ensure your application respects the API's rate limits to avoid service interruptions and maintain compliance with the API's usage policy.
  • Error Handling: Implement robust error handling to deal with network issues, server errors, or other unexpected conditions.

Conclusion

Congratulations on reaching the end of this CNS Case Portal API Guide. By now, you should have a solid understanding of how to effectively utilize the API to search and retrieve legal case information. The knowledge you've gained through this guide will enable you to integrate this powerful tool into your applications, enhancing your ability to access and analyze legal case data.

Key Takeaways

  1. API Authentication: Remember, authentication is crucial for accessing the API. Always ensure your Bearer Token is valid and manage its expiration appropriately.
  2. Constructing Queries: You've learned how to construct and send queries, customizing parameters to suit your specific needs.
  3. Response Handling: You can now confidently handle and interpret the API's responses, extracting valuable case information from the data provided.
  4. Efficient Pagination and Throttling: We've covered strategies for navigating through paginated results and managing the API's throttling limits, ensuring smooth and efficient data retrieval.

Moving Forward

  • Continued Learning: APIs can be dynamic, with new features and updates being introduced. Stay informed by regularly checking our documentation and updates.
  • Experimentation: Don't hesitate to experiment with different query parameters and response handling methods to fully leverage the API's capabilities.
  • Feedback and Support: Your feedback is invaluable. If you have suggestions, questions, or require support, please reach out via [email protected].

Final Thoughts

The CNS Case Portal API opens a gateway to a rich repository of legal case data. Whether you're developing legal research tools, analytical platforms, or simply exploring legal data, this API is a key resource in your toolkit. We're excited to see how you'll use it to drive your projects and innovations.

Happy coding! 🚀👩‍💻👨‍💻