Integration Guide

Quick Start

Get started with OpenPIIMap data integration in under 5 minutes.

1. Access JSON Files

Use our static JSON endpoints or clone the repository.

View Countries

2. Fetch Data

Use simple HTTP requests to access privacy law data.

View Examples

3. Integrate

Process the data in your compliance workflows.

See Use Cases

Tip

OpenPIIMap operates as a static site with JSON data files. No authentication required - simply fetch the data you need.

Data Structure

Understanding the JSON data structure for effective integration.

Countries Data

Access detailed information about privacy laws by country.

// Fetch countries data
fetch('/json/countries.json')
  .then(response => response.json())
  .then(data => {
    console.log(data.germany); // Access Germany's GDPR data
  });

Data Structure:

{
  "germany": {
    "name": "Germany",
    "framework": "GDPR",
    "categories": [
      {
        "name": "Personal Identifiers",
        "examples": ["Full Name", "Email Address", "Phone Number"]
      }
    ],
    "rights": ["Access", "Rectification", "Erasure"],
    "penalties": {
      "administrative_fines": "Up to €20M or 4% of global turnover"
    }
  }
}

Frameworks Data

Get framework-specific information across multiple jurisdictions.

// Fetch frameworks data
fetch('/json/frameworks.json')
  .then(response => response.json())
  .then(data => {
    console.log(data.gdpr); // Access GDPR framework details
  });

Common Use Cases

Real-world scenarios where OpenPIIMap data integration adds value to your systems.

Compliance Checking

Automatically verify if your data handling practices comply with local privacy laws.

async function checkCompliance(userLocation, dataTypes) {
  const countries = await fetch('/json/countries.json').then(r => r.json());
  const countryLaw = countries[userLocation.toLowerCase()];
  
  if (!countryLaw) return { compliant: false, reason: 'Unknown jurisdiction' };
  
  const violations = dataTypes.filter(type => 
    countryLaw.categories.some(cat => 
      cat.examples.includes(type) && cat.restrictions
    )
  );
  
  return {
    compliant: violations.length === 0,
    framework: countryLaw.framework,
    violations: violations
  };
}

Automate compliance verification

Support multiple jurisdictions

Data Masking Rules

Apply appropriate data masking based on jurisdiction and data sensitivity.

async function getMaskingRules(country) {
  const countries = await fetch('/json/countries.json').then(r => r.json());
  const law = countries[country.toLowerCase()];
  
  return law?.categories.map(category => ({
    category: category.name,
    fields: category.examples,
    maskingRequired: category.sensitive || false,
    retentionPeriod: category.retention || 'indefinite'
  })) || [];
}

User Rights Management

Implement user rights based on their jurisdiction's privacy laws.

async function getUserRights(userCountry) {
  const countries = await fetch('/json/countries.json').then(r => r.json());
  const law = countries[userCountry.toLowerCase()];
  
  return law?.rights || ['Access']; // Default to basic access right
}

Implementation Examples

Step-by-step implementation guides for different programming languages.

1

JavaScript/Node.js Implementation

class OpenPIIMapClient {
  constructor(baseUrl = 'https://openpiimap.org') {
    this.baseUrl = baseUrl;
    this.cache = new Map();
  }
  
  async getCountries() {
    if (this.cache.has('countries')) {
      return this.cache.get('countries');
    }
    
    const response = await fetch(`${this.baseUrl}/json/countries.json`);
    const data = await response.json();
    this.cache.set('countries', data);
    return data;
  }
  
  async getCountryLaw(country) {
    const countries = await this.getCountries();
    return countries[country.toLowerCase()] || null;
  }
  
  async getFrameworks() {
    if (this.cache.has('frameworks')) {
      return this.cache.get('frameworks');
    }
    
    const response = await fetch(`${this.baseUrl}/json/frameworks.json`);
    const data = await response.json();
    this.cache.set('frameworks', data);
    return data;
  }
}

2

Python Implementation

import requests
import json
from typing import Dict, Optional

class OpenPIIMapClient:
    def __init__(self, base_url: str = "https://openpiimap.org"):
        self.base_url = base_url
        self.cache = {}
    
    def get_countries(self) -> Dict:
        if 'countries' not in self.cache:
            response = requests.get(f"{self.base_url}/json/countries.json")
            response.raise_for_status()
            self.cache['countries'] = response.json()
        return self.cache['countries']
    
    def get_country_law(self, country: str) -> Optional[Dict]:
        countries = self.get_countries()
        return countries.get(country.lower())
    
    def get_frameworks(self) -> Dict:
        if 'frameworks' not in self.cache:
            response = requests.get(f"{self.base_url}/json/frameworks.json")
            response.raise_for_status()
            self.cache['frameworks'] = response.json()
        return self.cache['frameworks']

3

Usage Example

// Initialize client
const client = new OpenPIIMapClient();

// Check if email processing is compliant in Germany
async function checkEmailCompliance() {
  const germanyLaw = await client.getCountryLaw('germany');
  
  if (germanyLaw) {
    console.log(`Framework: ${germanyLaw.framework}`);
    console.log(`User Rights: ${germanyLaw.rights.join(', ')}`);
    
    // Check if email is considered PII
    const emailCategory = germanyLaw.categories.find(cat => 
      cat.examples.includes('Email Address')
    );
    
    if (emailCategory) {
      console.log(`Email is PII under: ${emailCategory.name}`);
    }
  }
}

Best Practices

Guidelines for effective and efficient integration of OpenPIIMap data.

Performance

Cache JSON responses to avoid repeated downloads
Use conditional requests with ETags when available
Consider downloading and hosting data locally for high-volume applications

Data Freshness

Check for updates periodically as privacy laws evolve
Subscribe to GitHub repository notifications for changes
Implement graceful fallbacks for missing jurisdictions

Error Handling

Handle network failures gracefully with cached data
Validate data structure before processing
Log compliance decisions for audit trails

Table of Contents