Enhance Geographical Data Access with State and City Information

[donprecious]

This pull request introduces significant enhancements to the RESTCountries.NET.Services library, specifically aimed at expanding our geographical data offerings to include detailed state and city information. This extension is designed to complement the existing RestCountriesService by adding RestStateService, while ensuring that the new service seamlessly integrates with the library's current structure and usage patterns.

Key Changes:

1. Introduction of RestStateService: A new static class that provides efficient, read-only access to states and cities data, preloaded from an embedded JSON resource. This service allows for retrieving lists of states within a specified country and lists of cities within a given state or state-country combination.

2. Unique Identification for States: To address potential state code duplication across different countries, state access now utilizes a concatenated key pattern ({countryCode}:{stateCode}). This ensures unique identification of states and resolves ambiguity in state data retrieval.

3. Integration with RestCountriesService: Exposed state and city information through RestCountriesService via new wrapper methods. This approach maintains a unified interface for users, allowing access to both country and state-level data through a single service.

4. Optimized Data Access: Implemented the use of dictionaries for storing and accessing state and city information, significantly improving the time required to retrieve records. This optimization ensures rapid data retrieval, enhancing the overall performance and user experience of the library.

Rationale: The expansion into state and city data was driven by community feedback and the observed need for a more granular level of geographical information. The decision to use a concatenated key pattern for state identification stems from the necessity to handle state code duplications gracefully, ensuring our library remains robust and reliable for global data access. The use of dictionaries for data storage and access was a strategic choice aimed at optimizing performance, making data retrieval operations both fast and efficient for library users.

Implications for Users: Users can now access detailed state and city information directly through RestCountriesService, enhancing the library's utility with minimal changes to existing usage patterns. The new key pattern for state identification ({countryCode}:{stateCode}) ensures that users can reliably access state information without confusion or conflicts. The optimization of data access through dictionaries significantly reduces data retrieval times, providing a smoother and more responsive experience when accessing geographical information.

Breaking Changes: None: This update has been carefully designed to enhance the library's functionality without introducing breaking changes. Existing users of RestCountriesService will experience no disruption in service; new methods have been added to extend functionality without altering any existing interfaces or expected behaviors.

Testing: Comprehensive unit tests have been added to verify the correctness of the new state and city data retrieval functionalities, both in isolation and as integrated with the existing country service. Tests cover both positive scenarios and negative cases, ensuring the library behaves as expected under various conditions.

How to Test: Please refer to the updated unit tests in RestCountriesServiceTests for examples on how to use the new functionalities. For existing users, no changes are required unless state or city information is needed, in which case the new methods in RestCountriesService can be utilized directly.

[egbakou]

Hi @donprecious Thanks for the PR.

I'm a bit concerned about the size of the dataset 🤔

[donprecious]

@egbakou Would you suggest we move this to extended nugget package such as RESTCountries.State.NET, so users who needs it would download it.

On Sun, Feb 25, 2024, 12:12 PM Laurent Egbakou @.***> wrote:

Hi @donprecious https://github.com/donprecious Thanks for the PR.

I'm a bit concerned about the size of the data set 🤔

— Reply to this email directly, view it on GitHub https://github.com/egbakou/RESTCountries.NET/pull/28#issuecomment-1962897470, or unsubscribe https://github.com/notifications/unsubscribe-auth/AIMCUFTMK37YN57TMRYSEPLYVMMBPAVCNFSM6AAAAABDOAFXZCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRSHA4TONBXGA . You are receiving this because you were mentioned.Message ID: @.***>

[donprecious]

@egbakou another approach would be to compress the data set .

On Sun, 25 Feb 2024 at 12:14, precious iyeritufu @.***> wrote:

Would you suggest we move this to extended nugget package such as RESTCountries.State.NET, so users who needs it would download it.

On Sun, Feb 25, 2024, 12:12 PM Laurent Egbakou @.***> wrote:

Hi @donprecious https://github.com/donprecious Thanks for the PR.

I'm a bit concerned about the size of the data set 🤔

— Reply to this email directly, view it on GitHub https://github.com/egbakou/RESTCountries.NET/pull/28#issuecomment-1962897470, or unsubscribe https://github.com/notifications/unsubscribe-auth/AIMCUFTMK37YN57TMRYSEPLYVMMBPAVCNFSM6AAAAABDOAFXZCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRSHA4TONBXGA . You are receiving this because you were mentioned.Message ID: @.***>

[donprecious]

@egbakou upon compression its now 840KB, from the way i wrote the code, if the states is needed it pulls it to the memory, we can decompress and put it in memory if needed by the user, let me know your thoughts.

[image: image.png]

On Sun, 25 Feb 2024 at 12:20, precious iyeritufu @.***> wrote:

another approach would be to compress the data set .

On Sun, 25 Feb 2024 at 12:14, precious iyeritufu @.***> wrote:

Would you suggest we move this to extended nugget package such as RESTCountries.State.NET, so users who needs it would download it.

On Sun, Feb 25, 2024, 12:12 PM Laurent Egbakou @.***> wrote:

Hi @donprecious https://github.com/donprecious Thanks for the PR.

I'm a bit concerned about the size of the data set 🤔

— Reply to this email directly, view it on GitHub https://github.com/egbakou/RESTCountries.NET/pull/28#issuecomment-1962897470, or unsubscribe https://github.com/notifications/unsubscribe-auth/AIMCUFTMK37YN57TMRYSEPLYVMMBPAVCNFSM6AAAAABDOAFXZCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRSHA4TONBXGA . You are receiving this because you were mentioned.Message ID: @.***>

[egbakou]

@egbakou Would you suggest we move this to extended nugget package such as RESTCountries.State.NET, so users who needs it would download it. … On Sun, Feb 25, 2024, 12:12 PM Laurent Egbakou @.> wrote: Hi @donprecious https://github.com/donprecious Thanks for the PR. I'm a bit concerned about the size of the data set 🤔 — Reply to this email directly, view it on GitHub <#28 (comment)>, or unsubscribe https://github.com/notifications/unsubscribe-auth/AIMCUFTMK37YN57TMRYSEPLYVMMBPAVCNFSM6AAAAABDOAFXZCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRSHA4TONBXGA . You are receiving this because you were mentioned.Message ID: @.>

It's a good idea, but the issue remains; the dataset is approximately 3.5MB. Additionally, to prevent duplication, the dataset should adhere to the format found here: https://github.com/egbakou/RESTCountries.NET/issues/23.

[egbakou]

Before compressing, the dataset needs enhancement. Will look into this.

[donprecious]

Before compressing, the dataset needs enhancement. Will look into this.

ok, you can look into the dataset and suggest what we can remove to reduce it, i will work on compressing and decompressing it, please note that i may or maynot need to install another nuget package that will handle the decompression. i will see if i can do it without having to install a different library for that

[donprecious]

@egbakou i have compressed the datasource and modified the implementation, Please take a look at it.