get_ilan_ad_detail

Instructions

Implementation Reference

• ihale_mcp.py:540-554 (handler)

  Primary MCP tool handler for get_ilan_ad_detail. Registered via @mcp.tool decorator. Defines input schema via Annotated parameter. Executes by calling IlanClient.get_ad_detail and returns the result.

  @mcp.tool
  async def get_ilan_ad_detail(
      ad_id: Annotated[str, "Advertisement ID from ilan.gov.tr search results"]
  ) -> Dict[str, Any]:
      """
      Get detailed information for a specific advertisement from ilan.gov.tr.
  
      Returns: title, content (HTML and Markdown), advertiser info, location,
      categories, filters, hit count, and other advertisement metadata.
      """
  
      # Use the client to get ad detail
      result = await ilan_client.get_ad_detail(ad_id)
  
      return result

• ilan_client.py:241-359 (helper)

  Core implementation logic in IlanClient.get_ad_detail. Performs API request to https://www.ilan.gov.tr/api/api/services/app/AdDetail/GetAdDetail, handles SSL, converts HTML content to Markdown using MarkItDown, formats categories/filters/advertiser info, and structures the full response dictionary.

  async def get_ad_detail(
      self,
      ad_id: str
  ) -> Dict[str, Any]:
      """Get detailed information for a specific advertisement"""
  
      ssl_context = self._create_ssl_context()
  
      try:
          # Make GET request with query parameter
          async with httpx.AsyncClient(
              timeout=30.0,
              verify=ssl_context,
              http2=False,
              limits=httpx.Limits(max_keepalive_connections=5, max_connections=10)
          ) as client:
              response = await client.get(
                  f"{self.base_url}{self.detail_endpoint}",
                  params={"id": ad_id},
                  headers=self.headers
              )
              response.raise_for_status()
              response_data = response.json()
  
          # Check if successful
          if not response_data.get("success", False):
              return {
                  "error": "API returned unsuccessful response",
                  "message": response_data.get("error", "Unknown error")
              }
  
          # Extract result
          result = response_data.get("result", {})
  
          if not result:
              return {
                  "error": "No detail found",
                  "ad_id": ad_id
              }
  
          # Extract HTML content
          html_content = result.get("content", "")
  
          # Convert HTML to Markdown
          markdown_content = None
          if html_content:
              try:
                  # Initialize markdown converter
                  markitdown = MarkItDown()
                  # Create BytesIO from HTML content
                  html_bytes = BytesIO(html_content.encode('utf-8'))
                  conversion_result = markitdown.convert_stream(html_bytes, file_extension=".html")
                  markdown_content = conversion_result.text_content if conversion_result else None
              except Exception as e:
                  print(f"Warning: Failed to convert HTML to markdown: {e}")
                  markdown_content = None
  
          # Format categories
          categories = []
          for cat in result.get("categories", []):
              categories.append({
                  "id": cat.get("taxId"),
                  "name": cat.get("name"),
                  "slug": cat.get("slug")
              })
  
          # Format filters
          ad_type_filters = []
          for filter_item in result.get("adTypeFilters", []):
              ad_type_filters.append({
                  "key": filter_item.get("key"),
                  "value": filter_item.get("value")
              })
  
          # Build response
          return {
              "ad_detail": {
                  "id": result.get("id"),
                  "ad_no": result.get("adNo"),
                  "title": result.get("title"),
                  "content_html": html_content,
                  "content_markdown": markdown_content,
                  "city": result.get("addressCityName"),
                  "county": result.get("addressCountyName"),
                  "advertiser": {
                      "name": result.get("advertiserName"),
                      "code": result.get("advertiserCode"),
                      "logo": result.get("advertiserLogo")
                  },
                  "source": {
                      "name": result.get("adSourceName"),
                      "code": result.get("adSourceCode"),
                      "logo": result.get("adSourceLogoPath")
                  },
                  "url": result.get("urlStr"),
                  "full_url": f"https://www.ilan.gov.tr{result.get('urlStr', '')}",
                  "categories": categories,
                  "filters": ad_type_filters,
                  "statistics": {
                      "hit_count": result.get("hitCount", 0),
                      "is_archived": result.get("isArchived", False),
                      "is_bik": result.get("isBikAd", False)
                  }
              },
              "success": True
          }
  
      except httpx.HTTPStatusError as e:
          return {
              "error": f"API request failed with status {e.response.status_code}",
              "message": str(e),
              "ad_id": ad_id
          }
      except Exception as e:
          return {
              "error": "Request failed",
              "message": str(e),
              "ad_id": ad_id
          }