Skip to main content

ICC API Overview

This document provides an overview of the International Code Council (ICC) public API that PermitProof integrates with to fetch building code data.

Base URL​

https://codes.iccsafe.org/api

API Endpoints​

The ICC API provides several endpoints for accessing building code content:

1. Search API​

Endpoint: /search/search-results

Purpose: Search for ICC books and codes by category, year, type, and other parameters.

Method: GET

Query Parameters:

  • category - Filter by category (e.g., "2021 I-Codes")
  • search - Search query string
  • page - Page number (1-based)
  • limit - Results per page (default: 20, max: 100)
  • year - Filter by publication year
  • type - Filter by document type

Example Request:

curl "https://codes.iccsafe.org/api/search/search-results?category=2021%20I-Codes&page=1&limit=100" \
  -H "Accept: application/json"

Example Response:

{
  "data": [
    {
      "document_id": "2217",
      "title": "2021 International Building Code",
      "document_slug": "IBC2021P1",
      "year": "2021",
      "categories": ["2021 I-Codes"],
      "type": "code"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_results": 45,
    "per_page": 100
  }
}

Implementation: IccSearchClient.java

2. Book Info API​

Endpoint: /content/info/{documentId}

Purpose: Get detailed metadata for a specific ICC book/document.

Method: GET

Path Parameters:

  • documentId - The ICC document ID (e.g., "2217", "3757", "3701")

Example Request:

curl "https://codes.iccsafe.org/api/content/info/2217" \
  -H "Accept: application/json"

Example Response:

{
  "document_id": "2217",
  "title": "2021 International Building Code",
  "document_slug": "IBC2021P1",
  "year": "2021",
  "publisher": "International Code Council",
  "isbn": "978-1-60983-920-1",
  "page_count": 756,
  "categories": ["2021 I-Codes", "Building Codes"],
  "description": "The 2021 International Building Code..."
}

Implementation: IccBookClient.fetchBookInfo()

3. Chapters API​

Endpoint: /content/chapters/{documentId}

Purpose: Get the table of contents (chapter structure) for a specific ICC book.

Method: GET

Path Parameters:

  • documentId - The ICC document ID

Example Request:

curl "https://codes.iccsafe.org/api/content/chapters/3757" \
  -H "Accept: application/json"

Example Response:

{
  "document_id": "3757",
  "chapters": [
    {
      "chapter_number": 1,
      "chapter_title": "SCOPE AND ADMINISTRATION",
      "chapter_content_id": "35712404",
      "sections": [
        {
          "section_id": "IRC2021P3_Ch01_SecR101",
          "section_number": "R101",
          "section_title": "SCOPE AND GENERAL REQUIREMENTS"
        }
      ]
    }
  ]
}

Implementation: IccChapterBrowser.java, IccBookClient.fetchBookChapterIndex()

4. Chapter XML/HTML Content API​

Endpoint: /content/chapter-xml/{documentId}/{chapterContentId}

Purpose: Get the full HTML content for a specific chapter.

Method: GET

Path Parameters:

  • documentId - The ICC document ID
  • chapterContentId - The chapter's content ID (from Chapters API)

Example Request:

curl "https://codes.iccsafe.org/api/content/chapter-xml/3757/35712404" \
  -H "Accept: application/json"

Example Response:

"<div class=\"chapter\"><h1>CHAPTER 1</h1><h2>SCOPE AND ADMINISTRATION</h2>...</div>"

Note: The API returns escaped HTML as a JSON string. The content must be unescaped before use.

Implementation: IccContentClient.java

5. Snippet API​

Endpoint: /snippet/get-snippet

Purpose: Get HTML content for a specific code section snippet.

Method: GET

Query Parameters:

  • hash - The document hash (section ID, e.g., "IRC2021P2_Pt03_Ch07_SecR702")
  • document - The document ID

Example Request:

curl "https://codes.iccsafe.org/api/snippet/get-snippet?hash=IRC2021P2_Pt03_Ch07_SecR702&document=2241" \
  -H "Accept: application/json"

Example Response:

{
  "content": {
    "content": "<div class=\"section\"><h3>R702</h3><p>Section content...</p></div>"
  }
}

Implementation: IccGetSnippetClient.java

Common Book IDs​

Document IDCodeYearEdition
2217International Building Code (IBC)2021-
3123International Building Code (IBC)2021New Jersey
3701California Building Code (CBC)2022Part 4
3815Florida Building Code (FBC)2023Building
3757International Residential Code (IRC)2021Part 3
3100ICC/ANSI A117.12017Accessibility
1156ICC 3002017Standard

API Client Architecture​

PermitProof implements a layered client architecture for ICC API integration:

Client Classes​

  1. IccSearchClient - Search and discover ICC books

    • Search by category, year, type
    • Load/save search results to filesystem
    • Extract document IDs from search results

  2. IccBookClient - Fetch complete book data

    • Fetch book info (metadata)
    • Fetch chapter index (table of contents)
    • Fetch all chapter HTML content
    • Configurable pause between requests (rate limiting)

  3. IccChapterBrowser - Navigate book structure

    • Parse chapter hierarchy
    • Map chapter numbers to content IDs
    • Resolve section paths

  4. IccContentClient - Fetch chapter HTML content

    • Retrieve chapter XML/HTML
    • Unescape and format HTML
    • Save to filesystem

  5. IccGetSnippetClient - Fetch section snippets

    • Retrieve individual section content
    • Parse nested JSON responses
    • Extract and format HTML

Data Storage Structure​

Downloaded ICC data is stored in the following structure:

api/icc/
├── content/
│   ├── info/
│   │   ├── {document_id}.json          # Pretty-printed book metadata
│   │   └── {document_id}.raw.json      # Raw API response
│   ├── chapters/
│   │   ├── {document_id}.json          # Pretty-printed chapter index
│   │   └── {document_id}.raw.json      # Raw API response
│   └── chapter-xml/
│       └── {document_id}/
│           ├── {chapter_content_id}.html  # Chapter 1 HTML
│           ├── {chapter_content_id}.html  # Chapter 2 HTML
│           └── ...                         # All chapters
└── codes/
    └── {jurisdiction}/
        └── search-results.json          # Saved search results

Rate Limiting​

The ICC API does not have published rate limits, but PermitProof implements conservative rate limiting to be respectful:

Default Pause Settings:

  • Minimum: 3000ms (3 seconds)
  • Maximum: 5000ms (5 seconds)
  • Randomization: Random pause between min and max to avoid patterns

Configurable via Builder Pattern:

IccBookClient client = new IccBookClient.Builder(documentId, fileSystemHandler)
    .pauseRange(2000, 4000)  // Custom: 2-4 seconds
    .build();

Authentication​

The ICC public API endpoints used by PermitProof do not require authentication. All endpoints are publicly accessible.

Note: ICC also has premium/authenticated APIs that are not currently used by PermitProof.

Error Handling​

HTTP Status Codes​

  • 200 OK: Successful request
  • 404 Not Found: Document or chapter not found
  • 429 Too Many Requests: Rate limit exceeded (not observed, but handled)
  • 500 Server Error: ICC API internal error

Client-Side Handling​

The PermitProof ICC clients implement:

  • Retry logic: Automatic retries with exponential backoff
  • Caching: Skip fetching if file already exists locally
  • Validation: Check for missing or malformed responses
  • Graceful degradation: Continue processing other books/chapters on individual failures

Usage Examples​

Search for Books​

# Using CLI
cli/codeproof.sh icc-search --category "2021 I-Codes" --all

# Programmatic
IccSearchClient client = new IccSearchClient();
SearchResult result = client.searchByCategory("2021 I-Codes", 1, 100);

Fetch Complete Book​

# Using CLI
cli/codeproof.sh icc-book-fetcher 2217 3757 --filesystem GCS

# Programmatic
IccBookClient client = new IccBookClient.Builder("2217", fileSystemHandler)
    .pauseRange(3000, 5000)
    .build();
client.fetch();  // Fetches info, chapters, and all HTML content

Browse Chapter Structure​

IccChapterBrowser browser = IccChapterBrowser.getById(fileSystemHandler, "3757");
String contentId = browser.getChapterNumericalContentId(1);  // Get Chapter 1 content ID
List<Chapter> chapters = browser.getChapters();

API Limitations​

  1. No Bulk Download: Must fetch books individually
  2. No Webhooks: No notification of content updates
  3. No Versioning: No API to detect when content changes
  4. HTML Escaping: Content is escaped and requires unescaping
  5. No Search Within Book: Must download full book for section-level search

Integration with PermitProof​

PermitProof uses the ICC API to:

  1. Discover Available Codes: Search API to find relevant building codes
  2. Download Code Content: Fetch complete books for offline analysis
  3. Build RAG Corpus: Process downloaded content for semantic search
  4. Code Applicability Analysis: Match architectural plans against code sections
  5. Compliance Reporting: Generate compliance reports based on code requirements

External Resources​