0
# Date Search
1

2
Search functionality for finding and parsing multiple dates within text documents. Automatically detects date patterns in natural language text and extracts them as datetime objects with optional language detection information.
3

4
## Capabilities
5

6
### Text Date Search
7

8
Find and parse all date expressions within a text string, supporting automatic language detection and customizable parsing settings.
9

10
```python { .api }
11
def search_dates(text, languages=None, settings=None, 
12
                 add_detected_language=False, detect_languages_function=None):
13
    """
14
    Find all substrings of the given string which represent date and/or time and parse them.
15

16
    Parameters:
17
    - text (str): A string in natural language which may contain date and/or time expressions
18
    - languages (list, optional): List of two letters language codes (e.g. ['en', 'es'])
19
    - settings (dict, optional): Configure customized behavior using Settings
20
    - add_detected_language (bool): Include detected language in results
21
    - detect_languages_function (function, optional): Custom language detection function
22

23
    Returns:
24
    list: List of tuples containing (date_substring, datetime_object) or
25
          (date_substring, datetime_object, detected_language) if add_detected_language=True
26
          Returns None if no dates can be parsed are found
27

28
    Raises:
29
    ValueError: Unknown Language
30
    """
31
```
32

33
**Usage Examples:**
34

35
```python
36
from dateparser.search import search_dates
37

38
# Basic date search
39
text = "The first artificial Earth satellite was launched on 4 October 1957."
40
dates = search_dates(text)
41
# Returns: [('on 4 October 1957', datetime.datetime(1957, 10, 4, 0, 0))]
42

43
# Multiple dates in text
44
text = "The client arrived on March 3rd, 2004 and returned on May 6th 2004"
45
dates = search_dates(text)
46
# Returns: [('on March 3rd, 2004', datetime.datetime(2004, 3, 3, 0, 0)),
47
#           ('on May 6th 2004', datetime.datetime(2004, 5, 6, 0, 0))]
48

49
# With language detection
50
dates = search_dates(text, add_detected_language=True)
51
# Returns: [('on March 3rd, 2004', datetime.datetime(2004, 3, 3, 0, 0), 'en'),
52
#           ('on May 6th 2004', datetime.datetime(2004, 5, 6, 0, 0), 'en')]
53

54
# Specific languages
55
text = "El evento fue el 15 de enero de 2023"
56
dates = search_dates(text, languages=['es'])
57
# Returns: [('15 de enero de 2023', datetime.datetime(2023, 1, 15, 0, 0))]
58

59
# With custom settings
60
from dateparser.conf import Settings
61
settings = Settings(PREFER_DATES_FROM='future', TIMEZONE='UTC')
62
dates = search_dates(text, settings=settings)
63
```
64

65
### Advanced Search Class
66

67
Lower-level search functionality for custom implementations and advanced search scenarios.
68

69
```python { .api }
70
class DateSearchWithDetection:
71
    """
72
    Core search functionality with automatic language detection.
73
    """
74
    
75
    def search_dates(self, text, languages=None, settings=None, 
76
                     detect_languages_function=None):
77
        """
78
        Search for dates in text with language detection.
79
        
80
        Parameters:
81
        - text (str): Text to search for dates
82
        - languages (list, optional): Language codes to use
83
        - settings (dict, optional): Parsing settings
84
        - detect_languages_function (function, optional): Custom language detection
85
        
86
        Returns:
87
        dict: Dictionary with 'Dates' and 'Language' keys
88
        """
89
    
90
    def preprocess_text(self, text, languages):
91
        """
92
        Preprocess text before date search.
93
        
94
        Parameters:
95
        - text (str): Input text
96
        - languages (list): Language codes
97
        
98
        Returns:
99
        str: Preprocessed text
100
        """
101
```
102

103
**Usage Examples:**
104

105
```python
106
from dateparser.search.search import DateSearchWithDetection
107

108
# Create search instance
109
search_engine = DateSearchWithDetection()
110

111
# Search with custom processing
112
text = "Meeting scheduled for next Friday and the presentation on January 15th"
113
result = search_engine.search_dates(text, languages=['en'])
114
dates = result.get('Dates')
115
language = result.get('Language')
116

117
# Batch processing multiple texts
118
texts = [
119
    "Event on December 1st, 2023",
120
    "Conference from March 15 to March 17, 2024",
121
    "Deadline is tomorrow"
122
]
123

124
all_dates = []
125
for text in texts:
126
    preprocessed = search_engine.preprocess_text(text, ['en'])
127
    result = search_engine.search_dates(preprocessed, languages=['en'])
128
    if result.get('Dates'):
129
        all_dates.extend(result['Dates'])
130
```
131

132
### Search Utilities
133

134
Helper functions for processing search results and working with date patterns.
135

136
```python { .api }
137
def date_is_relative(translation):
138
    """
139
    Check if a date translation represents a relative date.
140
    
141
    Parameters:
142
    - translation (str): Translated date string
143
    
144
    Returns:
145
    bool: True if date is relative (e.g., 'tomorrow', '2 days ago')
146
    """
147
```
148

149
**Usage Examples:**
150

151
```python
152
from dateparser.search.search import date_is_relative
153

154
# Check if dates are relative
155
is_relative = date_is_relative("2 days ago")  # True
156
is_relative = date_is_relative("January 15, 2023")  # False
157

158
# Filter relative dates from search results
159
from dateparser.search import search_dates
160

161
text = "The meeting was yesterday and the deadline is January 15, 2023"
162
dates = search_dates(text)
163

164
relative_dates = []
165
absolute_dates = []
166

167
for date_text, date_obj in dates:
168
    if date_is_relative(date_text):
169
        relative_dates.append((date_text, date_obj))
170
    else:
171
        absolute_dates.append((date_text, date_obj))
172
```