inec 0.1.2

Method for accessing INEC data directly from Python

INEC Costa Rica - Python API Module

This module is a powerful Python wrapper designed to facilitate access, exploration, and downloading of microdata from the Instituto Nacional de Estadística y Censos (INEC) of Costa Rica. It allows researchers and data analysts to interact with the institutional catalog directly from their development environment.

---

1. Structure & Hierarchy

The module is organized into three main levels to navigate the INEC database:

Level	Manager Class	Description
Repositories	RepositoryManager	High-level collections (e.g., REGENAHO, ENIG, Censos).
Datasets	DatasetsManager	Specific studies or surveys defined by a year or round.
Variables	VariablesManager	Metadata and data dictionaries for columns within a dataset.

---

2. Initialization

To use this module, you must have an active account on the INEC portal.

Obtaining your API Key

1. Go to the INEC Profile Page.
2. Log in with your credentials.
3. Look for the API Key section to generate or copy your unique token.

Initialization

The autofill_msg parameter is used to automatically complete the "Purpose of Request" forms required by many datasets.

from inec import INECAPI

client = INECAPI(
    api_key="YOUR_API_KEY", 
    email="[e-mail]", 
    password="your_password", 
    autofill_msg='I want to analyze these variables for time-series research'
)

3. Usage Examples

Repositories (client.repositories)

# List all available repositories
repo = client.repositories.show()
print(repo)

# Automatically fetch and concatenate multiple years of DBs
# (Searches the 'REGENAHO' repository between 2023 and 2025)
dataset = client.repositories.get(repositoryid='REGENAHO', start_year=2023, end_year=2025)
print(dataset)
# "DATA INTEGRITY NOTICE: Performing blind concatenation of multiple datasets. "
# "This module does not validate schema consistency, column names, or data types "
# "across different years. Please verify that variables are harmonized before analysis."
# "'_source_idno' column is created by the module for track which file produce it"

Datasets (client.datasets)

# List all datasets
all_datasets = client.datasets.show()
print(all_datasets)

# Search for datasets within a repository
dataset = client.datasets.show(repositoryid='REGENAHO')
print(dataset)

# Download microdata using internal ID or IDNO string (you can find this ids in their website or using datasets.show() function)
df_1 = client.datasets.get(113)
df_2 = client.datasets.get("INEC-Enaho-2025")

# List resources (additional files, questionnaires, etc.) for a study
resources = client.datasets.resources(113)
print(resources)

Variables (client.variables)

# View summary of variables for a study (very general view...)
var_summary = client.variables.show(128)
print(var_summary)

# Get full dictionary (ID, description, and documentation links) using internal ID or IDNO string
variables_1 = client.variables.dictionary("INEC-Enaho-2025")
print(variables_1)

variables_2 = client.variables.dictionary(113)
print(variables_2)

4. Key Features

• Form Autofill: If a dataset requires a justification form, the module submits it automatically using your autofill_msg.

• Automatic Parsing: Detects .sav (SPSS), .dta (Stata), .csv, and .xlsx extensions and converts them instantly to Pandas DataFrames. (some xlsx could have multiple sheets, be aware of that)

• Session Management: Automatically handles cookie expiration and retries authentication if Unauthorized error occurs.

• Data Integrity: When using repositories.get(), a _source_idno column is added to help track the origin of each row in concatenated datasets.