feat: add license match api endpoint to public and operations API (#1557)

Author: davidgamez

api/.flake8

@@ -1,5 +1,5 @@
 [flake8]
 max-line-length = 120
-exclude = .git,__pycache__,__init__.py,.mypy_cache,.pytest_cache,venv,build,feeds_gen,database_gen
+exclude = .git,__pycache__,__init__.py,.mypy_cache,.pytest_cache,venv,.venv,build,feeds_gen,database_gen
 # Ignored because conflict with black
 extend-ignore = E203

api/.openapi-generator/FILES

@@ -25,6 +25,7 @@ src/feeds_gen/models/gbfs_endpoint.py
 src/feeds_gen/models/gbfs_feed.py
 src/feeds_gen/models/gbfs_validation_report.py
 src/feeds_gen/models/gbfs_version.py
+src/feeds_gen/models/get_matching_licenses_request.py
 src/feeds_gen/models/gtfs_dataset.py
 src/feeds_gen/models/gtfs_feed.py
 src/feeds_gen/models/gtfs_rt_feed.py
@@ -34,6 +35,7 @@ src/feeds_gen/models/license_base.py
 src/feeds_gen/models/license_rule.py
 src/feeds_gen/models/license_with_rules.py
 src/feeds_gen/models/location.py
+src/feeds_gen/models/matching_license.py
 src/feeds_gen/models/metadata.py
 src/feeds_gen/models/redirect.py
 src/feeds_gen/models/search_feed_item_result.py

api/src/feeds/impl/licenses_api_impl.py

@@ -1,13 +1,17 @@
 from typing import List, Optional
 
 from feeds_gen.apis.licenses_api_base import BaseLicensesApi
+from feeds_gen.models.get_matching_licenses_request import GetMatchingLicensesRequest
 from feeds_gen.models.license_with_rules import LicenseWithRules
 from feeds_gen.models.license_base import LicenseBase
+from feeds_gen.models.matching_license import MatchingLicense
+from shared.common.license_utils import resolve_license
 from shared.database.database import with_db_session
 from shared.database_gen.sqlacodegen_models import License as LicenseOrm
 from feeds.impl.error_handling import raise_http_error
 from shared.db_models.license_with_rules_impl import LicenseWithRulesImpl
 from shared.db_models.license_base_impl import LicenseBaseImpl
+from shared.db_models.matching_license_impl import MatchingLicenseImpl
 
 
 class LicensesApiImpl(BaseLicensesApi):
@@ -42,3 +46,19 @@ def get_licenses(self, limit: int, offset: int, db_session) -> List[LicenseBase]
             return [LicenseBaseImpl.from_orm(lic) for lic in results]
         except Exception as e:
             raise_http_error(500, f"Error retrieving licenses: {e}")
+
+    @with_db_session
+    def get_matching_licenses(
+        self,
+        get_matching_licenses_request: GetMatchingLicensesRequest,
+        db_session,
+    ) -> List[MatchingLicense]:
+        """Get the list of matching licenses based on the provided license URL"""
+        try:
+            domain_matching_licenses = resolve_license(
+                license_url=get_matching_licenses_request.license_url,
+                db_session=db_session,
+            )
+            return [MatchingLicenseImpl.from_domain(matching_license) for matching_license in domain_matching_licenses]
+        except Exception as e:
+            raise_http_error(500, f"Error retrieving matching licenses: {e}")

api/src/shared/common/db_utils.py

@@ -552,9 +552,6 @@ def normalize_url_str(url: str | None) -> str:
     u = re.sub(r"^www\.", "", u, flags=re.I)
     # remove trailing slashes
     u = re.sub(r"/+$", "", u)
-    if "/" in u:
-        host, rest = u.split("/", 1)
-        return host.lower() + "/" + rest
     return u.lower()
 
 

api/src/shared/common/license_utils.py

@@ -12,7 +12,36 @@
 
 @dataclass
 class MatchingLicense:
-    """Response structure for license URL resolution."""
+    """Response structure for license URL resolution.
+
+    Represents a matched license result from the resolution process, containing
+    identification, matching metadata, and confidence scoring.
+
+    Attributes:
+        license_id: Unique identifier for the license (typically SPDX ID)
+        license_url: Original license URL provided for resolution
+        normalized_url: URL after normalization (lowercased, trimmed, protocol removed)
+        match_type: Type of match performed. One of:
+            - 'exact': Direct match found in database
+            - 'heuristic': Matched via pattern-based rules (CC resolver, common patterns)
+            - 'fuzzy': Similarity-based match against same-host licenses
+            - 'none': No match found
+        confidence: Match confidence score (0.0-1.0)
+            - 1.0: Exact match
+            - 0.99: Creative Commons resolved
+            - 0.95: Pattern heuristic match
+            - 0.0-1.0: Fuzzy match score based on string similarity
+        spdx_id: SPDX License Identifier if matched (e.g., 'CC-BY-4.0', 'MIT')
+        matched_name: Human-readable name of the matched license
+        matched_catalog_url: Canonical URL from the license catalog/database
+        matched_source: Source of the match. One of:
+            - 'db.license': Exact match from database
+            - 'cc-resolver': Creative Commons license resolver
+            - 'pattern-heuristics': Generic pattern matching
+        notes: Additional context about the match (e.g., version normalization, locale detection)
+        regional_id: Regional/jurisdictional variant identifier for ported licenses
+            (e.g., 'CC-BY-2.1-jp' for Japan-ported Creative Commons)
+    """
 
     license_id: str
     license_url: str

api/src/shared/db_models/matching_license_impl.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from feeds_gen.models.matching_license import MatchingLicense as ApiMatchingLicense
+from shared.common.license_utils import MatchingLicense as DomainMatchingLicense
+
+
+class MatchingLicenseImpl(ApiMatchingLicense):
+    """Adapter between the internal MatchingLicense representation and the OpenAPI model.
+
+    This class converts the internal/shared ``MatchingLicense`` object (used by
+    ``shared.common.license_utils``) into the corresponding OpenAPI-generated
+    ``feeds_gen.models.matching_license.MatchingLicense`` model.
+    """
+
+    @classmethod
+    def from_domain(
+        cls,
+        matching_license: Optional[DomainMatchingLicense],
+    ) -> Optional[ApiMatchingLicense]:
+        """Convert a domain ``MatchingLicense`` into the OpenAPI model.
+
+        Returns ``None`` if ``matching_license`` is ``None``.
+        """
+        if matching_license is None:
+            return None
+
+        return cls(
+            license_id=matching_license.license_id,
+            license_url=matching_license.license_url,
+            normalized_url=matching_license.normalized_url,
+            match_type=matching_license.match_type,
+            confidence=matching_license.confidence,
+            spdx_id=matching_license.spdx_id,
+            matched_name=matching_license.matched_name,
+            matched_catalog_url=matching_license.matched_catalog_url,
+            matched_source=matching_license.matched_source,
+            regional_id=matching_license.regional_id,
+            notes=matching_license.notes,
+        )

api/tests/integration/test_database.py

@@ -174,8 +174,8 @@ def test_insert_and_select():
         ("https://www.example.com/path///", "example.com/path"),
         # Host only with scheme and www; trailing slash removed; host lowercased
         ("http://www.EXAMPLE.com/", "example.com"),
-        # Path case preserved (only host lowercased)
-        ("https://Example.com/Case/Sensitive", "example.com/Case/Sensitive"),
+        # All lowercased
+        ("https://Example.com/Case/Sensitive", "example.com/case/sensitive"),
         # None becomes empty string
         (None, ""),
         # Blank / whitespace-only becomes empty string

docs/DatabaseCatalogAPI.yaml

@@ -394,7 +394,36 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/LicenseWithRules"
-
+  /v1/licenses:match:
+    post:
+      description: Get the list of matching licenses based on the provided license URL
+      tags:
+        - "licenses"
+      operationId: getMatchingLicenses
+      security:
+        - ApiKeyAuth: []
+      requestBody:
+        description: Payload containing the license URL to match against the database.
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - license_url
+              properties:
+                license_url:
+                  description: The license URL to resolve and match against the database.
+                  type: string
+                  format: url
+                  example: https://creativecommons.org/licenses/by/4.0/deed.nl
+      responses:
+        "200":
+          description: The list of matching licenses if any.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MatchingLicenses"
 components:
   schemas:
     Redirect:
@@ -1331,6 +1360,87 @@ components:
       items:
         $ref: "#/components/schemas/LicenseBase"
 
+    MatchingLicense:
+      type: object
+      description: Matching a license
+      properties:
+        license_id:
+          description: Unique identifier for the license (typically SPDX ID)
+          type: string
+          example: CC-BY-4.0
+        license_url:
+          description: Original license URL provided for resolution
+          type: string
+          example: https://creativecommons.org/licenses/by/4.0/
+        normalized_url:
+          description: URL after normalization (lowercased, trimmed, protocol removed)
+          type: string
+          example: creativecommons.org/licenses/by/4.0
+        match_type:
+          description: >
+            Type of match performed. One of:
+              - 'exact': Direct match found in database
+              - 'heuristic': Matched via pattern-based rules (CC resolver, common patterns)
+              - 'fuzzy': Similarity-based match against same-host licenses
+          type: string
+          example: heuristic
+        confidence:
+          description: >
+            Match confidence score (0.0-1.0), examples:
+              - 1.0: Exact match
+              - 0.99: Creative Commons resolved
+              - 0.95: Pattern heuristic match
+              - 0.0-1.0: Fuzzy match score based on string similarity
+          type: number
+          example: 0.99
+        spdx_id:
+          description: SPDX License Identifier if matched (e.g., 'CC-BY-4.0', 'MIT')
+          type: string
+          example: CC-BY-4.0
+        matched_name:
+          description: Human-readable name of the matched license
+          type: string
+          example: Creative Commons Attribution 4.0 International
+        matched_catalog_url:
+          description: Canonical URL from the license catalog/database
+          type: string
+          example: https://creativecommons.org/licenses/by/4.0/legalcode
+        matched_source:
+          description: >
+            Source of the match. Examples:
+              - 'db.license': Exact match from database
+              - 'cc-resolver': Creative Commons license resolver
+              - 'pattern-heuristics': Generic pattern matching
+          type: string
+          example: cc-resolver
+        notes:
+          description: Additional context about the match (e.g., version normalization, locale detection)
+          type: string
+          example: Detected locale/jurisdiction port 'nl'. SPDX does not list ported CC licenses; using canonical ID.
+        regional_id:
+          description: >
+            Regional/jurisdictional variant identifier for ported licenses
+              (e.g., 'CC-BY-2.1-jp' for Japan-ported Creative Commons)
+          type: string
+          example: CC-BY-4.0-nl
+      example:
+        license_id: CC-BY-4.0
+        license_url: https://creativecommons.org/licenses/by/4.0/deed.nl
+        normalized_url: creativecommons.org/licenses/by/4.0
+        match_type: heuristic
+        confidence: 0.99
+        spdx_id: CC-BY-4.0
+        matched_name: Creative Commons Attribution 4.0 International
+        matched_catalog_url: https://creativecommons.org/licenses/by/4.0/legalcode
+        matched_source: cc-resolver
+        notes: Detected locale/jurisdiction port 'nl'. SPDX does not list ported CC licenses; using canonical ID.
+        regional_id: CC-BY-4.0-nl
+
+    MatchingLicenses:
+      description: List of MatchingLicense
+      type: array
+      items: 
+        $ref: "#/components/schemas/MatchingLicense"
 
   parameters:
     status: