🇳🇵 Nepal Entity Service

Open Source, open data, and open API for Nepali public entities

Getting Started

This guide will help you get started with the Nepal Entity Service API. Whether you're building a web application, conducting research, or exploring Nepal's political landscape, this guide covers everything you need to know.

Installation

Using the Public API

The easiest way to use Nepal Entity Service is through the public API. No installation required - just make HTTP requests to the API endpoints.

Base URL: https://nes.newnepal.org/api

Note: If you're running your own instance locally, replace https://nes.newnepal.org/api with http://localhost:8195/api in all examples below.

Installing the Python Package

If you want to run your own instance or use the data maintainer interface:

Note: Still in the process of deploying to PyPI.

# Install with pip
pip install nepal-entity-service

# Or with poetry
poetry add nepal-entity-service

Running Your Own Instance

To run your own instance of the API:

# Clone the repository with submodules
git clone --recurse-submodules --depth 0 https://github.com/NewNepal-org/NepalEntityService.git
cd NepalEntityService

# If you already cloned without submodules, initialize them:
# git submodule update --init --recursive

# Install dependencies with poetry
poetry install

# Start the API server
poetry run nes server start

The API will be available at http://localhost:8195.

Your First API Call

Let's make your first API call to search for entities:

Using cURL

curl "https://nes.newnepal.org/api/entities?query=poudel"

Using Python

import requests

response = requests.get(
    "https://nes.newnepal.org/api/entities",
    params={"query": "poudel"}
)

data = response.json()
print(f"Found {data['total']} entities")

for entity in data['entities']:
    print(f"- {entity['names'][0]['en']['full']}")

Using JavaScript

fetch('https://nes.newnepal.org/api/entities?query=poudel')
  .then(response => response.json())
  .then(data => {
    console.log(`Found ${data.total} entities`);
    data.entities.forEach(entity => {
      console.log(`- ${entity.names[0].en.full}`);
    });
  });

Common Operations

Search for Entities

Search for entities by name (supports both English and Nepali):

# Search by English name
curl "https://nes.newnepal.org/api/entities?query=ram+chandra+poudel"

# Search by Nepali name
curl "https://nes.newnepal.org/api/entities?query=राम+चन्द्र+पौडेल"

Filter by Entity Type

Filter entities by type (person, organization, location):

# Get all persons
curl "https://nes.newnepal.org/api/entities?entity_type=person"

# Get all political parties
curl "https://nes.newnepal.org/api/entities?entity_type=organization&sub_type=political_party"

Get a Specific Entity

Retrieve a specific entity by its ID:

curl "https://nes.newnepal.org/api/entities/entity:person/ram-chandra-poudel"

Query Relationships

Find relationships for an entity:

# Get all relationships for an entity
curl "https://nes.newnepal.org/api/entities/entity:person/ram-chandra-poudel/relationships"

# Filter by relationship type
curl "https://nes.newnepal.org/api/entities/entity:person/ram-chandra-poudel/relationships?relationship_type=MEMBER_OF"

Get Version History

Retrieve the version history for an entity:

curl "https://nes.newnepal.org/api/entities/entity:person/ram-chandra-poudel/versions"

Pagination

All list endpoints support pagination using limit and offset parameters:

# Get first 10 results
curl "https://nes.newnepal.org/api/entities?limit=10&offset=0"

# Get next 10 results
curl "https://nes.newnepal.org/api/entities?limit=10&offset=10"

Response Format

All API responses follow a consistent JSON format:

{
  "entities": [...],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Error responses include detailed error information:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Entity not found"
  }
}

Rate Limiting

The public API has rate limits to ensure fair usage:

If you need higher limits, please contact us about dedicated access.

CORS Support

The API supports CORS (Cross-Origin Resource Sharing), allowing you to make requests from web applications:

// Works from any origin
fetch('https://nes.newnepal.org/api/entities')
  .then(response => response.json())
  .then(data => console.log(data));

Next Steps

Now that you've made your first API calls, explore:

Need Help?