Lexicala.NET

A modern .NET client library for the Lexicala Dictionary API. Lexicala provides comprehensive linguistic data including translations, definitions, pronunciations, and more across multiple languages.

Prerequisites

• .NET 8.0 or .NET 10.0 runtime
• A RapidAPI account with an API key for Lexicala (sign up at RapidAPI)

Installation

Install the package via NuGet:

dotnet add package Lexicala.NET

Or using the Package Manager Console:

Install-Package Lexicala.NET

Configuration

1. Obtain API Key

1. Sign up for a RapidAPI account at rapidapi.com
2. Subscribe to the Lexicala API
3. Copy your API key from the RapidAPI dashboard

2. Configure Your Application

Add the Lexicala configuration to your appsettings.json:

{
  "Lexicala": {
        "ApiKey": "your-rapidapi-key-here",
        "UseLiteEndpoints": false
  }
}

Set UseLiteEndpoints to true if your subscription only allows Lite entry/sense endpoints. When enabled, the client automatically uses:

• /search-entries-lite instead of /search-entries
• /entries-lite/{entryId} instead of /entries/{entryId}
• /senses-lite/{senseId} instead of /senses/{senseId}

3. Register Services

In your Program.cs (for .NET 6+):

using Lexicala.NET;

var builder = WebApplication.CreateBuilder(args);

// Register Lexicala services
builder.Services.RegisterLexicala(builder.Configuration);

var app = builder.Build();
// ... rest of your setup

Supported Frameworks

• .NET 8.0
• .NET 10.0

Getting Started

After configuration, you can inject ILexicalaClient or ILexicalaSearchParser into your services.

Basic Search Example

// Inject ILexicalaClient
public class TranslationService
{
    private readonly ILexicalaClient _client;

    public TranslationService(ILexicalaClient client)
    {
        _client = client;
    }

    public async Task<string> TranslateWordAsync(string word, string fromLang, string toLang)
    {
        var searchResponse = await _client.BasicSearchAsync(word, fromLang);
        if (searchResponse.Results.Any())
        {
            var entry = await _client.GetEntryAsync(searchResponse.Results.First().Id);
            // Translations is Dictionary<string, TranslationObject> keyed by 2-letter language code
            var sense = entry.Senses.FirstOrDefault(s => s.Translations.ContainsKey(toLang));
            if (sense is not null && sense.Translations.TryGetValue(toLang, out var translationObj))
            {
                return translationObj.Translation?.Text
                    ?? translationObj.Translations?.FirstOrDefault()?.Text
                    ?? "Translation not found";
            }
        }
        return "Word not found";
    }
}

Code Examples

Get Available Languages

var languagesResponse = await lexicalaClient.LanguagesAsync();
var globalLanguages = languagesResponse.Resources.Global;
Console.WriteLine($"Available languages: {string.Join(", ", globalLanguages.SourceLanguages)}");

Basic Search

// Search for "hello" in English
var searchResponse = await lexicalaClient.BasicSearchAsync("hello", "en");
foreach (var result in searchResponse.Results)
{
    var headwordText =
        result.Headword?.Headword?.Text
        ?? result.Headword?.HeadwordElementArray?.FirstOrDefault()?.Text
        ?? "(no headword)";

    Console.WriteLine($"Found: {headwordText} (ID: {result.Id})");
}

Advanced Search

var advancedRequest = new AdvancedSearchRequest
{
    Language = "en",
    SearchText = "run",
    Pos = "verb"  // Part of speech filter
};

var advancedResponse = await lexicalaClient.AdvancedSearchAsync(advancedRequest);
foreach (var result in advancedResponse.Results)
{
    var entry = await lexicalaClient.GetEntryAsync(result.Id);
    // Process detailed entry information
}

Using the Search Parser

The ILexicalaSearchParser provides a higher-level abstraction for easier parsing:

// Inject ILexicalaSearchParser
public class SearchService
{
    private readonly ILexicalaSearchParser _parser;

    public SearchService(ILexicalaSearchParser parser)
    {
        _parser = parser;
    }

    public async Task<SearchResultModel> SearchAndParseAsync(string term, string language)
    {
        return await _parser.SearchAsync(term, language);
    }
}

// Usage
var result = await searchService.SearchAndParseAsync("árbol", "es");
var englishSummary = result.Summary("en");  // "tree, shaft, post, mast"
foreach (var searchResult in result.Results)
{
    var definition = searchResult.Senses.FirstOrDefault()?.Definition;
    Console.WriteLine($"Definition: {definition}");
}

Get Entry Details

var entry = await lexicalaClient.GetEntryAsync("EN00001234");  // Example ID
foreach (var sense in entry.Senses)
{
    Console.WriteLine($"Sense: {sense.Definition}");
}
foreach (var headword in entry.Headwords)
{
    foreach (var pron in headword.Pronunciations)
    {
        Console.WriteLine($"Pronunciation: {pron.Value}");
    }
}

Testing with Swagger UI

The repository includes an ASP.NET Core minimal Web API demo host with Swagger UI for testing all endpoints.

1. Clone the repository and navigate to the demo API:

   cd source/Demo/Lexicala.NET.Demo.Api

2. Configure your Lexicala API key. Choose one of the following:

   Recommended: Use User Secrets

   dotnet user-secrets init
   dotnet user-secrets set "Lexicala:ApiKey" "your-rapidapi-key-here"

   Alternative: Edit appsettings.json

   Open appsettings.json in the demo API folder and add:

   {
     "Lexicala": {
             "ApiKey": "your-rapidapi-key-here",
             "UseLiteEndpoints": false
     }
   }

3. Run the application:

   dotnet run

4. Open Swagger UI in your browser:

   • HTTP: http://localhost:5000/swagger
   • HTTPS: https://localhost:5001/swagger

5. To use the Sense Sprint web app, see the Sense Sprint documentation for setup and gameplay details.

Available endpoints:

• GET /test - Test API connectivity
• GET /languages - Get available languages
• GET /search - Basic search
• GET /search-entries - Basic search with full entries
• GET /search-entries-lite - Basic search with full entries in lite mode (UseLiteEndpoints=true)
• GET /search-rdf - Basic search in RDF/JSON-LD format
• GET /search-definitions - Free-text search in definitions
• GET /fluky-search - Random word discovery
• GET /entries/{entryId} - Get dictionary entry by ID
• GET /entries-lite/{entryId} - Get dictionary entry by ID in lite mode (UseLiteEndpoints=true)
• GET /senses/{senseId} - Get sense by ID
• GET /senses-lite/{senseId} - Get sense by ID in lite mode (UseLiteEndpoints=true)
• GET /rdf/{entryId} - Get entry in RDF/JSON-LD format
• POST /search-advanced - Advanced search
• POST /search-entries-advanced - Advanced search with full entries
• POST /search-rdf-advanced - Advanced search in RDF/JSON-LD format

Missing endpoints compared to Rapid Api test console / Lexicala MCP tooling - these endpoints are NOT listed in the official documentation!:

• GET /abbreviations
• GET /reverse-abbreviations
• GET /antonyms
• GET /definitions
• GET /examples
• GET /frequencies
• GET /phrases
• GET /pronunciations
• GET /registers
• GET /semantic-categories
• GET /subcategorizations
• GET /synonyms
• GET /translate-to
• GET /translate-example
• GET /translate-phrase

For React frontend development, CORS is enabled for:

• http://localhost:3000
• http://localhost:5173

Sense Sprint Demo Game

A dedicated React + Vite frontend for a word guessing game is available at source/Demo/sense-sprint-web.

The web demo currently includes two game modes. Sense Sprint is the lower-cost mode. Translation Quiz makes more Lexicala calls per round because it has to source a word, fetch its entry, and build multiple distractor choices. If you are using a free evaluation subscription, use Translation Quiz sparingly.

1. Start the backend API (see Testing with Swagger UI above)

2. In another terminal, navigate to the frontend:

   cd source/Demo/sense-sprint-web

3. Install dependencies and start the dev server:

   PowerShell:

   npm.cmd install
   npm.cmd run dev

   Bash / Command Prompt:

   npm install
   npm run dev

4. Open the app at http://localhost:5173

For complete game documentation, features, and tips, see the Sense Sprint README.

Building from Source

1. Clone the repository:

   git clone https://github.com/HannoZ/Lexicala.NET.git
   cd Lexicala.NET

2. Build the solution:

    dotnet build source/Lexicala.NET.slnx

3. Run tests:

    dotnet test source/Lexicala.NET.slnx

The legacy source/Lexicala.NET.sln file has been removed in favor of source/Lexicala.NET.slnx.

Supported API Values

The library validates and supports these commonly used API parameter values:

• source values for FlukySearchAsync and AdvancedSearch*Async: global, password, random, multigloss
• Language parameters (language, sourceLanguage) must be 2-character language codes
• AdvancedSearchRequest.Page accepts values up to 1000
• AdvancedSearchRequest.Sample accepts values up to 1000
• AdvancedSearchRequest.PageLength accepts values between 1 and 30 (default 10)

API Coverage

The library implements the following Lexicala API endpoints:

Utility Endpoints

• /test - Test API connectivity
• /languages - Get available languages

Search Endpoints

• /search - Basic search
• /search-entries - Search with full entries
• /search-entries-lite - Search with full entries in lite mode (UseLiteEndpoints=true)
• /search-rdf - Search in RDF/JSON-LD format
• /search-definitions - Free-text search in definitions
• /fluky-search - Random word discovery

Advanced Search Endpoints

• /search-advanced - Advanced search with custom parameters
• /search-entries-advanced - Advanced search with full entries
• /search-rdf-advanced - Advanced search in RDF/JSON-LD format

Entry and Sense Endpoints

• /entries - Get entry details by ID
• /entries-lite - Get entry details by ID in lite mode (UseLiteEndpoints=true)
• /senses - Get sense details by ID
• /senses-lite - Get sense details by ID in lite mode (UseLiteEndpoints=true)
• /rdf - Get entry in RDF/JSON-LD format

For complete API documentation, visit the Lexicala API Documentation.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.