Metadata-Version: 2.1
Name: collins-dictionary-api-client
Version: 0.1.0
Summary: Client to the Collins dictionary API
Author-email: Daniel Martins Antunes <danoan2008@gmail.com>
License: MIT License
        
        Copyright (c) 2024, Daniel Martins Antunes
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Documentation, https://danoan.github.io/collins-dictionary-api-client
Project-URL: Issues, https://github.com/danoan/collins-dictionary-api-client/issues
Project-URL: Source, https://github.com/danoan/collins-dictionary-api-client
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: beautifulsoup4
Requires-Dist: lxml
Requires-Dist: requests

# Getting started with Collins Dictionary Api Client

Command Line Interface and python library to make requests to the [Collins dictionary API](https://www.collinsdictionary.com/collins-api).

- [Read the docs](https://danoan.github.io/collins-dictionary-api-client/)
- Link to [Collin API documentation](https://drive.google.com/file/d/1CmAR_eCxRCrkIShKRo4f2DrvQ-d-S7Og/view?usp=sharing)

## Installation

```bash
# Command line interface
$ pipx install collins-dictionary-api-client

# Library
$ pip install collins-dictionary-api-client
```

## Examples

```bash
$ collins-dictionary-api-client --secret-key <SECRET_KEY> search garden
{"resultNumber":69,"results":[{"entryLabel":"garden","entryUrl":"http://localhost/api/v1/dictionaries/english/entries/garden_1","entryId":"garden_1"}..."

```

Type `collins-dictionary-api-client --help` to see all available options.

## Methods available

The following methods are implemented in the client.

### search

Get a list of entry ids corresponding to the search term.

```json
{
    "resultNumber": 1,
    "results": [
        {
            "entryLabel": "legitim",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitim_1",
            "entryId": "legitim_1"
        }
    ],
    "dictionaryCode": "english",
    "currentPageIndex": 1,
    "pageNumber": 1
}
```

### did_you_mean

Get a list of suggestions corresponding to the input word.

The suggested words are close to the input word in a lexicographic sense.
For example, share a good portion of the prefix or the suffix.

```json
{
    "searchTerm": "legitim",
    "dictionaryCode": "english",
    "suggestions": [
        "legit",
        "legitimist",
        "legitimize",
        "legitimate",
        "flexitime",
        "legitimizer",
        "legitimator",
        "legitimiser",
        "gregatim",
        "legalism"
    ]
}
```

### get_best_matching

Get the metadata of the first entry found for the searched word.

```json
{
    "topics": [],
    "dictionaryCode": "english",
    "entryLabel": "legitim",
    "entryContent": "<div class=\"entry_container\"><div class=\"entry lang_en-gb\" id=\"legitim_1\"><span class=\"inline\"><h1 class=\"hwd\">legitim<\/h1><span> (<\/span><span class=\"pron\" type=\"\">ˈlɛdʒɪtɪm<\/span><span>)<\/span><\/span><div class=\"hom\" id=\"legitim_1.1\"><span class=\"gramGrp\"><span>   <\/span><span class=\"pos\">noun<\/span><\/span><div class=\"sense\"><span>     <\/span><span class=\"lbl\">Scots law<\/span><span> <\/span><span class=\"def\">the part of a person's moveable estate that is inherited by his or her children on that person's death<\/span><\/div><!-- End of DIV sense--><\/div><!-- End of DIV hom--><\/div><!-- End of DIV entry lang_en-gb--><\/div><!-- End of DIV entry_container-->\n",
    "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitim_1",
    "format": "html",
    "entryId": "legitim_1"
}
```

### get_entry

Get the first entry found for the searched word.

```json
{
    "topics": [],
    "dictionaryCode": "english",
    "entryLabel": "legit",
    "entryContent": "<div class=\"entry_container\"><div class=\"entry lang_en-gb\" id=\"legit_1\"><span class=\"inline\"><h1 class=\"hwd\">legit<\/h1><span> (<\/span><span class=\"pron\" type=\"\">lɪˈdʒɪt<a href=\"#\" class=\"playback\"><img src=\"https://api.collinsdictionary.com/external/images/redspeaker.gif?version=2016-11-09-0913\" alt=\"Pronunciation for legit\" class=\"sound\" title=\"Pronunciation for legit\" style=\"cursor: pointer\"/><\/a><audio type=\"pronunciation\" title=\"legit\"><source type=\"audio/mpeg\" src=\"https://api.collinsdictionary.com/media/sounds/sounds/e/en_/en_gb/en_gb_legit.mp3\"/>Your browser does not support HTML5 audio.<\/audio><\/span><span>)<\/span><span class=\"lbl\"><span> <\/span>slang<\/span><\/span><div class=\"hom\" id=\"legit_1.1\"><span class=\"gramGrp\"><span>   <\/span><span class=\"pos\">adjective<\/span><\/span><div class=\"sense\"><span class=\"sensenum\">     1 <\/span><span class=\"xr\"><span class=\"lbl\">short for<\/span><span> <\/span>\n                \n        \t\t<a data-resource=\"english\" data-topic=\"legitimate_1\" href=\"\">legitimate<\/a><\/span><\/div><!-- End of DIV sense--><\/div><!-- End of DIV hom--><div class=\"hom\" id=\"legit_1.2\"><span> <br/>▷ <\/span><span class=\"gramGrp\"><span class=\"pos\">noun<\/span><\/span><div class=\"sense\"><span class=\"sensenum\">     2 <\/span><span class=\"def\">legitimate or professionally respectable drama<\/span><\/div><!-- End of DIV sense--><\/div><!-- End of DIV hom--><\/div><!-- End of DIV entry lang_en-gb--><\/div><!-- End of DIV entry_container-->\n",
    "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legit_1",
    "format": "html",
    "entryId": "legit_1"
}
```

### get_pronunciations

Get a list of pronunciations.

Each pronunciation entry contains a URL to a mp3 file.

```json
[
    {
        "dictionaryCode": "english",
        "pronunciationUrl": "https://api.collinsdictionary.com/media/sounds/sounds/e/en_/en_gb/en_gb_legit.mp3",
        "lang": "uk",
        "entryId": "legit_1"
    }
]
```

### get_nearby_entries

Get a list of entries related to the input word.

The returned words or expressions are in the same semantic scope of the input word.

```json
{
    "nearbyFollowingEntries": [
        {
            "entryLabel": "legitim",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitim_1",
            "entryId": "legitim_1"
        },
        {
            "entryLabel": "legitimate",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitimate_1",
            "entryId": "legitimate_1"
        },
        {
            "entryLabel": "legitimator",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitimator_1",
            "entryId": "legitimator_1"
        },
        {
            "entryLabel": "legitimiser",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitimiser_1",
            "entryId": "legitimiser_1"
        },
        {
            "entryLabel": "legitimist",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitimist_1",
            "entryId": "legitimist_1"
        },
        {
            "entryLabel": "legitimistic",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitimistic_1",
            "entryId": "legitimistic_1"
        },
        {
            "entryLabel": "legitimize",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitimize_1",
            "entryId": "legitimize_1"
        },
        {
            "entryLabel": "legitimizer",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legitimizer_1",
            "entryId": "legitimizer_1"
        },
        {
            "entryLabel": "legless",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legless_1",
            "entryId": "legless_1"
        },
        {
            "entryLabel": "leglessness",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/leglessness_1",
            "entryId": "leglessness_1"
        }
    ],
    "dictionaryCode": "english",
    "nearbyPrecedingEntries": [
        {
            "entryLabel": "legionnaire's disease",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legionnaires-disease_1_1",
            "entryId": "legionnaires-disease_1_1"
        },
        {
            "entryLabel": "legislate",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legislate_1",
            "entryId": "legislate_1"
        },
        {
            "entryLabel": "legislation",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legislation_1",
            "entryId": "legislation_1"
        },
        {
            "entryLabel": "legislative",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legislative_1",
            "entryId": "legislative_1"
        },
        {
            "entryLabel": "legislative assembly",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legislative-assembly_1",
            "entryId": "legislative-assembly_1"
        },
        {
            "entryLabel": "legislative council",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legislative-council_1",
            "entryId": "legislative-council_1"
        },
        {
            "entryLabel": "legislator",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legislator_1",
            "entryId": "legislator_1"
        },
        {
            "entryLabel": "legislatorial",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legislatorial_1",
            "entryId": "legislatorial_1"
        },
        {
            "entryLabel": "legislature",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legislature_1",
            "entryId": "legislature_1"
        },
        {
            "entryLabel": "legist",
            "entryUrl": "http://localhost/api/v1/dictionaries/english/entries/legist_1",
            "entryId": "legist_1"
        }
    ],
    "entryId": "legit_1"
}
```


## Contributing

Please reference to our [contribution](https://danoan.github.io/collins-dictionary-api-client/contributing.html) and [code-of-conduct](https://danoan.github.io/collins-dictionary-api-client/code-of-conduct.html)
