Herold.at API

A TypeScript library for scraping data from Herold.at Gelbe Seiten (Austrian yellow pages). This package provides functions to search business listings, fetch categories, extract contact information, and get detailed business information.

Installation

npm install hr-api-ts
# or
pnpm add hr-api-ts
# or
yarn add hr-api-ts

Usage

Basic Import

import {
  searchListings,
  getEmailById,
  getInfo,
  getAutocompleteSuggestions,
} from "hr-api-ts";

Search Business Listings

import { searchListings } from "hr-api-ts";

const result = await searchListings({
  was: "arzt", // Search term (what to search for)
  position: "20", // Position/offset
  umkreis: "-1", // Radius (-1 = no limit)
  anzahl: "10", // Number of results
  sortierung: "relevanz", // Sort order: "relevanz", "name", "plz"
});

if (result.success) {
  console.log(result.data); // Array of ListingResult
  console.log(result.metadata); // Additional metadata
} else {
  console.error(result.error);
}

Get Detailed Business Information

import { getInfo } from "hr-api-ts";

const businessInfo = await getInfo("listing-id-here");

if (businessInfo.success) {
  console.log("Business Name:", businessInfo.data.name);
  console.log("Email:", businessInfo.data.email);
  console.log("Phone:", businessInfo.data.phone);
  console.log(
    "Address:",
    businessInfo.data.street,
    businessInfo.data.plz,
    businessInfo.data.city
  );
  console.log("Website:", businessInfo.data.website);
  console.log("Fax:", businessInfo.data.fax);
} else {
  console.error(businessInfo.error);
}

Get Email by Listing ID

import { getEmailById } from "hr-api-ts";

const emailResult = await getEmailById("listing-id-here");

if (emailResult.success && emailResult.data) {
  console.log("Email:", emailResult.data);
} else {
  console.log("No email found or error occurred");
}

Get Autocomplete Suggestions

import { getAutocompleteSuggestions } from "hr-api-ts";

const autocompleteResult = await getAutocompleteSuggestions("aut");

if (autocompleteResult.success) {
  console.log("Suggestions:", autocompleteResult.data);
  // Output: ["Auto", "Autoreparaturen", "Autoteile", "Autoverleih", ...]
} else {
  console.error("Autocomplete failed:", autocompleteResult.error);
}

Fetch Categories

import {
  fetchCategoryNamesById,
  fetchMainCategoryUrls,
  fetchAllSubcategoryNames,
  extractCategoryIdsFromUrl,
} from "hr-api-ts";

// Get category names by ID
const categories = await fetchCategoryNamesById("category-id");

// Get main category URLs
const mainCategories = await fetchMainCategoryUrls();

// Get all subcategory names
const allSubcategories = await fetchAllSubcategoryNames();

// Extract category IDs from a page URL
const categoryIds = await extractCategoryIdsFromUrl(
  "https://www.herold.at/gelbe-seiten/branchenbuch"
);

Types

ListingSearchParams

interface ListingSearchParams {
  was?: string; // Search term
  position?: string; // Position/offset
  umkreis?: string; // Radius (-1 = no limit)
  anzahl?: string; // Number of results
  sortierung?: string; // Sort order
  verwandt?: string; // Related search
}

ListingResult

interface ListingResult {
  id: string; // Unique listing ID
  name: string; // Business name
  website?: string; // Website URL (if available)
  email?: string; // Email (if available)
}

BusinessInfo

interface BusinessInfo {
  name?: string; // Business name
  email?: string; // Email address
  street?: string; // Street address
  city?: string; // City name
  plz?: string; // Postal code
  phone?: string; // Phone number
  fax?: string; // Fax number
  website?: string; // Website URL
}

AutocompleteResponse

interface AutocompleteResponse {
  vorschlaege: string[]; // Array of autocomplete suggestions
  werbung: null; // Advertising field (always null)
}

ScrapingResult

interface ScrapingResult<T> {
  data: T;
  success: boolean;
  error?: string;
  metadata?: {
    anzahlTreffer?: number;
    anzahlMehrTreffer?: number;
    gesamtanzahlTreffer?: number;
  };
}

Available Functions

Core Functions

• searchListings(params: ListingSearchParams) - Search for business listings
• getInfo(listingId: string) - Get detailed business information (name, email, phone, address, website, fax)
• getEmailById(listingId: string) - Get email for a specific listing (backward compatibility)
• getAutocompleteSuggestions(tag: string) - Get autocomplete suggestions for search terms
• fetchCategoryNamesById(categoryId: string) - Get category names by ID
• fetchMainCategoryUrls() - Get main category URLs
• extractCategoryIdsFromUrl(pageUrl: string) - Extract category IDs from a page
• fetchAllSubcategoryNames() - Get all subcategory names

Aliases (for backward compatibility)

• searchListingsByParams - Alias for searchListings
• getEmailByListingId - Alias for getEmailById
• getInfoByListingId - Alias for getInfo
• getCategorieNamesByID - Alias for fetchCategoryNamesById
• getMainCategories - Alias for fetchMainCategoryUrls
• getIdsByUrl - Alias for extractCategoryIdsFromUrl
• getAllSubcategories - Alias for fetchAllSubcategoryNames

Example Usage

import { searchListings, getInfo, getAutocompleteSuggestions } from "hr-api-ts";

async function findAndGetBusinessInfo() {
  // Get autocomplete suggestions first
  const suggestions = await getAutocompleteSuggestions("arzt");
  if (suggestions.success) {
    console.log("Available suggestions:", suggestions.data);
  }

  // Search for doctors
  const searchResult = await searchListings({
    was: "arzt",
    anzahl: "5",
    sortierung: "relevanz",
  });

  if (searchResult.success && searchResult.data.length > 0) {
    // Get detailed info for the first result
    const firstListing = searchResult.data[0];
    const businessInfo = await getInfo(firstListing.id);

    if (businessInfo.success) {
      console.log("Found business:", businessInfo.data);
    }
  }
}

CLI Usage

You can also run the package directly as a CLI tool:

# Build the project
pnpm build

# Run the example script
pnpm example

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

License

ISC

Disclaimer

This library is for educational and research purposes. Please respect the terms of service of Herold.at and use this library responsibly. Make sure to comply with their robots.txt and rate limiting policies.