Skip to main content
Choose the perfect format for your project. Each format is optimized for specific use cases and comes with different credit costs and integration patterns.

​
Format Overview

JSON

Free Format
  • Web applications
  • APIs and microservices
  • JavaScript/Node.js projects
  • Mobile app backends

CSV

+1 Credit
  • Spreadsheet analysis
  • Data science workflows
  • Excel/Google Sheets
  • BI tools and dashboards

XML

+2 Credits
  • Enterprise systems
  • SOAP APIs
  • Legacy system integration
  • Configuration files

YAML

+2 Credits
  • Configuration files
  • DevOps and CI/CD
  • Documentation
  • Human-readable data

SQL

+3 Credits
  • Database seeding
  • Data migration
  • Direct imports
  • Production deployments

​
JSON Format (Free)

The most popular format for modern web development. Perfect for APIs, web applications, and mobile backends.
  • Structure & Examples
  • Integration Examples
  • Best Practices
Clean, nested structure with logical grouping:
Sample Countries Export
{
  "countries": [
    {
      "name": "United States",
      "iso2": "US",
      "iso3": "USA", 
      "phonecode": "1",
      "currency": "USD",
      "currency_symbol": "$",
      "region": "Americas",
      "subregion": "Northern America",
      "latitude": 37.09024,
      "longitude": -95.712891,
      "emoji": "🇺🇸",
      "native": "United States"
    },
    {
      "name": "Canada", 
      "iso2": "CA",
      "iso3": "CAN",
      "phonecode": "1", 
      "currency": "CAD",
      "currency_symbol": "C$",
      "region": "Americas",
      "subregion": "Northern America", 
      "latitude": 56.130366,
      "longitude": -106.346771,
      "emoji": "🇨🇦",
      "native": "Canada"
    }
  ],
  "metadata": {
    "total_countries": 2,
    "export_date": "2024-01-15T10:30:00Z",
    "fields": ["name", "iso2", "iso3", "phonecode", "currency"],
    "version": "1.0"
  }
}
Multi-dataset structure:
Countries + States Export
{
  "countries": [
    {
      "name": "United States",
      "iso2": "US",
      "states_count": 50
    }
  ],
  "states": [
    {
      "name": "California", 
      "iso2": "CA",
      "country_code": "US",
      "latitude": 36.778261,
      "longitude": -119.417932
    }
  ],
  "metadata": {
    "countries_count": 1,
    "states_count": 50,
    "export_date": "2024-01-15T10:30:00Z"
  }
}

​
CSV Format (+1 Credit)

Perfect for spreadsheet analysis, data science workflows, and business intelligence tools.
  • Structure & Format
  • Excel Integration
  • Python/Pandas Usage
Clean, standardized CSV with headers:
Countries Export
name,iso2,iso3,phonecode,currency,currency_symbol,region,subregion,latitude,longitude,capital,emoji
United States,US,USA,1,USD,$,Americas,Northern America,37.09024,-95.712891,Washington,🇺🇸
Canada,CA,CAN,1,CAD,C$,Americas,Northern America,56.130366,-106.346771,Ottawa,🇨🇦
United Kingdom,GB,GBR,44,GBP,£,Europe,Northern Europe,55.378051,-3.435973,London,🇬🇧
Multi-sheet structure for combined datasets:
countries.csv
name,iso2,currency,capital
United States,US,USD,Washington
Canada,CA,CAD,Ottawa
states.csv
name,iso2,country_code,latitude,longitude
California,CA,US,36.778261,-119.417932
Texas,TX,US,31.968599,-99.901813

​
XML Format (+2 Credits)

Ideal for enterprise systems, SOAP APIs, and legacy system integrations that require structured, schema-validated data.
  • Structure & Schema
  • Enterprise Integration
  • XPath Queries
Well-formed XML with proper namespaces:
Countries Export
<?xml version="1.0" encoding="UTF-8"?>
<csc:export xmlns:csc="https://countrystatecity.in/schemas/v1" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="https://countrystatecity.in/schemas/v1 csc-schema.xsd">
  
  <csc:metadata>
    <csc:export_date>2024-01-15T10:30:00Z</csc:export_date>
    <csc:version>1.0</csc:version>
    <csc:total_records>247</csc:total_records>
  </csc:metadata>
  
  <csc:countries>
    <csc:country>
      <csc:basic_info>
        <csc:name>United States</csc:name>
        <csc:native_name>United States</csc:native_name>
        <csc:iso2>US</csc:iso2>
        <csc:iso3>USA</csc:iso3>
        <csc:emoji>🇺🇸</csc:emoji>
      </csc:basic_info>
      
      <csc:contact_info>
        <csc:phonecode>1</csc:phonecode>
        <csc:capital>Washington</csc:capital>
      </csc:contact_info>
      
      <csc:economic_info>
        <csc:currency code="USD" symbol="$">US Dollar</csc:currency>
        <csc:currency_name>US Dollar</csc:currency_name>
      </csc:economic_info>
      
      <csc:geographic_info>
        <csc:region>Americas</csc:region>
        <csc:subregion>Northern America</csc:subregion>
        <csc:coordinates>
          <csc:latitude>37.09024</csc:latitude>
          <csc:longitude>-95.712891</csc:longitude>
        </csc:coordinates>
      </csc:geographic_info>
      
      <csc:cultural_info>
        <csc:nationality>American</csc:nationality>
        <csc:native_name>United States</csc:native_name>
      </csc:cultural_info>
      
      <csc:timezones>
        <csc:timezone>America/New_York</csc:timezone>
        <csc:timezone>America/Chicago</csc:timezone>
        <csc:timezone>America/Denver</csc:timezone>
        <csc:timezone>America/Los_Angeles</csc:timezone>
      </csc:timezones>
    </csc:country>
  </csc:countries>
</csc:export>

​
YAML Format (+2 Credits)

Human-readable format perfect for configuration files, documentation, and DevOps workflows.
  • Structure & Format
  • Configuration Usage
  • Application Integration
Clean, hierarchical YAML structure:
Countries Export
metadata:
  export_date: "2024-01-15T10:30:00Z"
  version: "1.0"
  total_countries: 247
  fields:
    - name
    - iso2
    - currency
    - region

countries:
  - name: "United States"
    iso2: "US"
    iso3: "USA"
    basic_info:
      native_name: "United States"
      emoji: "🇺🇸"
      capital: "Washington"
    
    contact_info:
      phonecode: "1"
      tld: ".us"
    
    economic_info:
      currency: "USD"
      currency_symbol: "$"
      currency_name: "US Dollar"
    
    geographic_info:
      region: "Americas"
      subregion: "Northern America"
      coordinates:
        latitude: 37.09024
        longitude: -95.712891
    
    cultural_info:
      nationality: "American"
      native_name: "United States"
    
    timezones:
      - "America/New_York"
      - "America/Chicago"
      - "America/Denver"
      - "America/Los_Angeles"

  - name: "Canada"
    iso2: "CA" 
    iso3: "CAN"
    basic_info:
      native_name: "Canada"
      emoji: "🇨🇦"
      capital: "Ottawa"
    
    economic_info:
      currency: "CAD"
      currency_symbol: "C$"
      currency_name: "Canadian Dollar"
    
    geographic_info:
      region: "Americas"
      subregion: "Northern America"
      coordinates:
        latitude: 56.130366
        longitude: -106.346771

​
SQL Format (+3 Credits)

Ready-to-execute SQL statements for direct database imports, perfect for production deployments and data migrations.
  • Generated SQL Structure
  • Database Integration
  • Application Integration
Complete database schema with relationships:
Countries & States Export
-- CSC Export Generated SQL
-- Generated on: 2024-01-15T10:30:00Z
-- Version: 1.0
-- Contains: Countries, States

-- Drop existing tables (optional)
-- DROP TABLE IF EXISTS states;
-- DROP TABLE IF EXISTS countries;

-- Create countries table
CREATE TABLE IF NOT EXISTS countries (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    iso2 CHAR(2) UNIQUE NOT NULL,
    iso3 CHAR(3) UNIQUE NOT NULL,
    numeric_code VARCHAR(10),
    phonecode VARCHAR(20),
    capital VARCHAR(255),
    currency CHAR(3),
    currency_name VARCHAR(100),
    currency_symbol VARCHAR(10),
    tld VARCHAR(10),
    native VARCHAR(255),
    region VARCHAR(100),
    subregion VARCHAR(100),
    latitude DECIMAL(10, 8),
    longitude DECIMAL(11, 8),
    emoji VARCHAR(10),
    emojiU VARCHAR(50),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    flag BOOLEAN DEFAULT TRUE,
    
    -- Indexes for performance
    INDEX idx_countries_iso2 (iso2),
    INDEX idx_countries_iso3 (iso3),
    INDEX idx_countries_region (region),
    INDEX idx_countries_currency (currency)
);

-- Create states table
CREATE TABLE IF NOT EXISTS states (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    country_id INTEGER NOT NULL,
    country_code CHAR(2) NOT NULL,
    fips_code VARCHAR(10),
    iso2 VARCHAR(10),
    type VARCHAR(50),
    latitude DECIMAL(10, 8),
    longitude DECIMAL(11, 8),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    flag BOOLEAN DEFAULT TRUE,
    wikiDataId VARCHAR(50),
    
    -- Foreign key relationship
    FOREIGN KEY (country_id) REFERENCES countries(id) ON DELETE CASCADE,
    
    -- Indexes
    INDEX idx_states_country_id (country_id),
    INDEX idx_states_country_code (country_code),
    INDEX idx_states_name (name)
);

-- Insert countries data
INSERT INTO countries (
    name, iso2, iso3, numeric_code, phonecode, capital, currency, 
    currency_name, currency_symbol, tld, native, region, subregion, 
    latitude, longitude, emoji, emojiU
) VALUES
('United States', 'US', 'USA', '840', '1', 'Washington', 'USD', 'US dollar', '$', '.us', 'United States', 'Americas', 'Northern America', 37.09024000, -95.71289100, '🇺🇸', 'U+1F1FA U+1F1F8'),
('Canada', 'CA', 'CAN', '124', '1', 'Ottawa', 'CAD', 'Canadian dollar', '$', '.ca', 'Canada', 'Americas', 'Northern America', 56.13036600, -106.34677100, '🇨🇦', 'U+1F1E8 U+1F1E6'),
('United Kingdom', 'GB', 'GBR', '826', '44', 'London', 'GBP', 'British pound', '£', '.uk', 'United Kingdom', 'Europe', 'Northern Europe', 55.37805100, -3.43597300, '🇬🇧', 'U+1F1EC U+1F1E7');

-- Insert states data (with proper country_id references)
INSERT INTO states (
    name, country_id, country_code, fips_code, iso2, type, 
    latitude, longitude, wikiDataId
) VALUES
('Alabama', (SELECT id FROM countries WHERE iso2 = 'US'), 'US', '01', 'AL', 'state', 32.31823140, -86.90229800, 'Q173'),
('Alaska', (SELECT id FROM countries WHERE iso2 = 'US'), 'US', '02', 'AK', 'state', 66.16044020, -153.36914700, 'Q797'),
('Alberta', (SELECT id FROM countries WHERE iso2 = 'CA'), 'CA', NULL, 'AB', 'province', 53.93327060, -116.57664600, 'Q1951');

-- Create views for common queries
CREATE VIEW countries_with_stats AS
SELECT 
    c.*,
    COUNT(s.id) as states_count,
    AVG(s.latitude) as avg_state_latitude,
    AVG(s.longitude) as avg_state_longitude
FROM countries c
LEFT JOIN states s ON c.id = s.country_id
GROUP BY c.id;

-- Create stored procedures for common operations
DELIMITER //
CREATE PROCEDURE GetCountryWithStates(IN country_code CHAR(2))
BEGIN
    SELECT c.*, s.name as state_name, s.iso2 as state_iso2
    FROM countries c
    LEFT JOIN states s ON c.id = s.country_id
    WHERE c.iso2 = country_code
    ORDER BY s.name;
END //
DELIMITER ;

-- Grant permissions (adjust as needed)
-- GRANT SELECT, INSERT, UPDATE ON countries TO 'app_user'@'%';
-- GRANT SELECT, INSERT, UPDATE ON states TO 'app_user'@'%';

​
Format Selection Guide

Choosing the right format can save you credits and development time. Use this decision tree:
1

Define Your Use Case

Ask yourself:
  • Where will this data be used?
  • Who will consume the data?
  • What tools do you have available?
  • Do you need real-time updates?
2

Consider Integration Complexity

Development Time vs Credit Cost:
Recommendation: JSON (Free)
  • Native JavaScript support
  • Easy API integration
  • No additional parsing needed
  • Perfect for React, Vue, Angular
Recommendation: CSV (+1 credit)
  • Excel/Google Sheets ready
  • Pandas compatibility
  • Tableau/PowerBI import
  • Statistical analysis tools
Recommendation: XML (+2 credits)
  • Schema validation
  • SOAP web services
  • Legacy system integration
  • Structured data requirements
Recommendation: YAML (+2 credits)
  • Human-readable format
  • Kubernetes configs
  • CI/CD pipelines
  • Documentation-friendly
Recommendation: SQL (+3 credits)
  • Direct database import
  • Proper relationships
  • Production-ready
  • Migration-friendly
3

Calculate Total Cost

Final Cost Formula:
Total Credits = Dataset Cost + Format Cost

Examples:
- Countries (1) + JSON (0) = 1 credit
- Countries (1) + States (2) + CSV (1) = 4 credits  
- Cities (3) + SQL (3) = 6 credits

​
Best Practices by Format

  • JSON Optimization
  • CSV Best Practices
  • SQL Production Tips
Performance Tips:
Lazy Loading
// Don't load all data at once for large datasets
class GeoDataLoader {
  async loadCountries() {
    if (!this.countriesCache) {
      const response = await fetch('/data/countries.json');
      this.countriesCache = await response.json();
    }
    return this.countriesCache;
  }
  
  async loadStatesByCountry(countryCode) {
    const cacheKey = `states_${countryCode}`;
    if (!this.statesCache[cacheKey]) {
      const response = await fetch(`/data/states/${countryCode}.json`);
      this.statesCache[cacheKey] = await response.json();
    }
    return this.statesCache[cacheKey];
  }
}
Memory Management:
Efficient Processing
// Process large JSON files in chunks
function processCountriesInBatches(countries, batchSize = 100) {
  const results = [];
  for (let i = 0; i < countries.length; i += batchSize) {
    const batch = countries.slice(i, i + batchSize);
    const processed = batch.map(processCountry);
    results.push(...processed);
    
    // Allow garbage collection between batches
    if (i % 1000 === 0) {
      await new Promise(resolve => setTimeout(resolve, 0));
    }
  }
  return results;
}
Need help choosing a format? Consider your primary use case:
  • Quick prototyping: Start with JSON (free)
  • Data analysis: Use CSV for spreadsheet compatibility
  • Production database: Invest in SQL for proper setup
  • Configuration management: YAML for readability