The Basic Meeting List Toolbox

Search Parameters

Try The New Semantic Workshop!

Parameters for the “switcher=GetSearchResults” Value

NOTE: These are all case-sensitive!

NOTE: There are a number of possible values for each parameter. When we say “array,” we mean that the same parameter is repeated, with an open/close bracket ([]) between it and the values. For example: meeting_ids=123 means search only for one meeting, whose ID is “123”, while meeting_ids[]=123&meeting_ids[]=456 indicates that two meetings are being sought by ID: 123, and 456.

These are possible parameters that you append to the URL described previously. You append these as URL arguments. For example, searching for all meetings that occur on Saturday and Sunday, and returning the results as XML, would look like this:

http://bmlt.newyorkna.org/main_server/client_interface/xml/?switcher=GetSearchResults&weekdays[]=1&weekdays[]=7

The same search, returning a geographic result (KML) would look like this (remember that we don’t specify the switcher parameter in the geographic searches):

http://bmlt.newyorkna.org/main_server/client_interface/kml/?weekdays[]=1&weekdays[]=7

Geographic Location

We don’t use address lookups. Instead, we geolocate the meetings via the longitude and latitude assigned to each meeting.

NOTE: When you specify a negative integer (NOT floating-point number) as a value for geo_width or geo_width_km, you are telling the server to select its own radius. The value of the integer indicates roughly how many meetings you want included in the search. The actual number is almost certain to vary from the requested amount, so consider it more of a “ball park” figure.

geo_width
A floating point number. This is the radius (not diameter) of the search, in MILES (not Kilometers). If this is negative, then it should be an integer, and that indicates an auto-radius is requested to find the number of meetings in the integer. This is mutually exclusive with the geo_width_km parameter. You can use one, but not both.
geo_width_km
A floating point number. This is the radius (not diameter) of the search, in KILOMETERS (not Miles). If this is negative, then it should be an integer, and that indicates an auto-radius is requested to find the number of meetings in the integer. This is mutually exclusive with the geo_width parameter. You can use one, but not both.
long_val
If one of the two radius specifiers (geo_width or geo_width_km) is set, this is applied. This is a floating point number that specifies the longitude, in degrees, of the center of the search radius.
lat_val
If one of the two radius specifiers (geo_width or geo_width_km) is set, this is applied. This is a floating point number that specifies the latitude, in degrees, of the center of the search radius.

String Searches

String searches in the BMLT are done “across the board.” The search goes through all of the meeting fields (like address fields and formats, as well as the meeting name). Additionally, we use metaphone for English and Spanish searches (It can be disabled). Metaphone is a “sounds like” algorithm that can help to compensate for misspellings and whatnot. It can, however, interfere with very specific text searches (for example, it will think that “While” and “Wyle” are the same word).

SearchString
A string. If this is specified, then all the string fields of the meetings specified by the above criteria will be searched for the string. By default, if the language supports metaphone (sound like search), then that is used.
SearchStringAll
A boolean (1 or 0). If nonzero, then all of the words in the search string will have to be matched for a meeting to qualify.
You do not need to specify 0 as a value. Simply not including this parameter is the same as a false value.
SearchStringExact
A boolean (1 or 0). If nonzero, metaphone will not be used, and the spelling must be exact.
You do not need to specify 0 as a value. Simply not including this parameter is the same as a false value.
StringSearchIsAnAddress
A boolean (1 or 0). Nonzero means that the given string should not be checked against any of the fields in the meeting data. Instead, it is to be considered a submission to the Google Maps geocode, and will be used to determine a center point in a local search.
You do not need to specify 0 as a value. Simply not including this parameter is the same as a false value.
SearchStringRadius
A positive floating-point, or negative integer.
If specified, the radius of the search around the address. The units are in whatever the server units are for the Root Server’s server’s native setting (can be miles or kilometers).
Negative numbers must always be integers, and specify a rough target number of meetings for auto-radius. The rules are the same as with the geo_width or geo_width_km parameters. This is mutually exclusive with the geo_width or geo_width_km parameters. You can only use one of these parameters at a time.
This parameter is ignored if StringSearchIsAnAddress is false.

Weekdays

This parameter specifies which day of the week the meeting starts on.

weekdays (Can be specified as an array, with more than one value)
This is an array of positive (or negative) integers, from 1 to 7. Each integer represents a weekday (1 -> Sunday, 7 -> Saturday).
A positive integer means that the search will look specifically for meetings that occur on that weekday.
If the integer is negative (preceded by a minus sign -), then the criteria will be to look for meetings that don’t occur on that weekday.

Start Time

The following values specify a start time “window.” The meeting must start on, or after StartsAfter[H/M], and can start no later than StartsBefore[H/M]

StartsAfterH
A positive integer between 0 and 23. The hour of the minimal start time for meetings, in military time.
StartsAfterM
A positive integer between 0 and 59. The minute of the minimal start time for meetings, in military time.
StartsBeforeH
A positive integer between 0 and 23. The hour of the maximal start time for meetings, in military time.
StartsBeforeM
A positive integer between 0 and 59. The minute of the maximal start time for meetings, in military time.

Meeting Duration

The following values specify a time duration “window.” The meeting can last no longer than MaxDuration[H/M], and no less than MinDuration[H/M].

MinDurationH
A positive integer. This is the number of hours in the minimal duration.
MinDurationM
A positive integer. This is the number of minutes in the minimal duration.
MaxDurationH
A positive integer. This is the number of hours in the maximal duration.
MaxDurationM
A positive integer. This is the number of minutes in the maximal duration.

Sorting Results

There are a few basic “default” searches available for most searches, but we also have the ability to specify sorts more intricately.

The Default Sorts

sort_key
The keys by which to sort. These are established at the root server. The default keys are:

weekday
This sorts first, by weekday, then by town, then by borough, then by neighborhood, and finally by start time. This is the default.
time
This sorts first, by weekday, then by start time, then by town, then by borough, and finally by neighborhood.
town
This sorts first, by town, then by borough, then by neighborhood, then by weekday, and finally, by start time.
state
This sorts first, by state (province), town, then by borough, then by neighborhood, then by weekday, and finally, by start time.
state_weekday
This sorts first, by weekday, then by state (province), town, then by borough, then by neighborhood, and finally by start time.
sort_dir
This is the direction of the sort. It can be:

asc
Ascending (Default)
desc
Descending
sort_results_by_distance
Specifying this overrides other sort criteria, but it only applies to radius/geographic searches. If specified, then results are sorted by distance from the longitude/latitude provided as the search center. Closest first, most distant, last.

The Specific Sort

sort_keys
This is a comma-separated list of values (not an array).
If this parameter is specified, the sort_key and sort_dir parameters are both ignored.
Each value is the name of a meeting data field in the database.
NOTE: Not all of these will work in predictable ways! You’ll need to experiment, in order to determine the best parameters. Different Root Servers may behave in different ways, as these rely heavily on the content of the server. Some of these will be downright useless.
The default values available are:

id_bigint
This is the BMLT ID of the meeting
weekday_tinyint
This is the day of the week
start_time
This is the time of day that the meeting begins
duration_time
This is the meeting duration
formats
The list of format codes associated with the meeting
lang_enum
The language used for the meeting
service_body_bigint
The Service body for the meeting (Note: Sorts by Service body ID, not name)
longitude
latitude
The longitude and latitude
worldid_mixed
The NAWS Committee Code
meeting_name
The name of the meeting
location_text
The name of the building/facility in which the meeting gathers
location_info
Any extra information associated with the meeting
location_street
The street address of the meeting
location_city_subsection
The borough (or “Ku,” if you are in Tokyo) of the city
location_neighborhood
The neighborhood of the city (like “Harlem” or “Brookline”)
location_municipality
The name of the town
location_sub_province
The county
location_province
The state or province
location_postal_code_1
The zip code, or postal code
location_nation
The nation
comments
Any comments associated with the meeting
train_lines
Any train line information associated with the meeting
bus_lines
Any bus line information associated with the meeting
desc
If this is supplied, then the search direction will be descending (ascending is default)

Specifying Values for Specific Fields

There is a mechanism to specify a field in the meeting record, and search only for meetings with a specific value in that field. This is done by the use of two parameters:

meeting_key
This specifies which field is to be checked. The possible values are:

meeting_name
The name of the meeting
location_text
The name of the building/facility in which the meeting gathers
location_info
Any extra information associated with the meeting
location_street
The street address of the meeting
location_city_subsection
The borough (or “Ku,” if you are in Tokyo) of the city
location_neighborhood
The neighborhood of the city (like “Harlem” or “Brookline”)
location_municipality
The name of the town
location_sub_province
The county
location_province
The state or province
location_postal_code_1
The zip code, or postal code
location_nation
The nation
comments
Any comments associated with the meeting
train_lines
Any train line information associated with the meeting
bus_lines
Any bus line information associated with the meeting
meeting_key_value
This is the value to match for that meeting key. This can use metaphone for string fields.
meeting_key_match_case
If 1, the case must match. Default is 0. NOTE: Setting this to 1 also stops the metaphone search.
meeting_key_contains
If this is set to 0, then the string must be complete. Default is 1 (contains).

New In Root Server Version 2.5.3: The “simple_other_fields” Parameter

The “Other” fields (customized fields, like Contact Addresses and Train/Bus Lines) are normally sent in a manner that combines their prompt and their value.

The syntax is “<PROMPT>#@-@#<VALUE>“.

If you add “&simple_other_fields=1” to the parameter list, only the value will be returned.

New In Root Server Version 2.8.8: The “Meeting Ends Before” Parameters

Starting with Root Server version 2.8.8, there’s a couple of new parameters that you can add that specify that meetings that meet the search criteria must END before or at a given time.

EndsBeforeH
A positive integer between 0 and 23. The hour of the maximal end time for meetings, in military time.
EndsBeforeM
A positive integer between 0 and 59. The minute of the maximal end time for meetings, in military time.

Service Bodies

You can search for meetings that belong to specific Service bodies. You do this by specifying the Service bodies by their BMLT ID

services (Can be specified as an array, with more than one value)
This is an array of positive integers. Each integer represents the ID of a Service Body. A positive integer means that the search will look specifically for meetings that contain that Service Body ID. If the integer is negative (preceded by a minus sign -), then the criteria will be to look for meetings that don’t contain that ID. If no ‘services’ values are given, then the search will not use the Service Body field as a search criteria.

Individual Meetings

You can search for meetings by their BMLT ID

meeting_ids (Can be specified as an array, with more than one value)
This is an array of positive integers. Each integer represents the ID of a meeting. A positive integer means that the search will look specifically for meetings that contain that ID (only 1 result per ID, of course). If the integer is negative (preceded by a minus sign -), then the criteria will be to look for meetings that don’t contain that ID. If no ‘meeting_ids’ values are given, then the search will not use the ID field as a search criteria.

Languages

You can also search for meetings by their language

langs (Can be specified as an array, with more than one value)
This is an array of 2-character strings. The search will look specifically for meetings that are in the indicated language[s]. If the language is preceded by a minus sign -, then the criteria will be to look for meetings that are not in that language. If no ‘langs’ values are given, then the search will not use the lang_enum field as a search criteria.

Filtering For Only Certain Data Fields

This parameter allows you to specify that only certain fields be returned, as opposed to everything in the meeting record.

NOTE: This does not apply to the geographic searches, which will ignore this parameter. They already know what they need to return.

data_field_key
This is a comma-separated list of values (not an array). Each one is a data field. If they are included in this list, then they will be returned.
The default values available are:

id_bigint
This is the BMLT ID of the meeting
weekday_tinyint
This is the day of the week
start_time
This is the time of day that the meeting begins
duration_time
This is the meeting duration
formats
The list of format codes associated with the meeting
lang_enum
The language used for the meeting
service_body_bigint
The Service body for the meeting (Note: Sorts by Service body ID, not name)
longitude
latitude
The longitude and latitude
worldid_mixed
The NAWS Committee Code
meeting_name
The name of the meeting
location_text
The name of the building/facility in which the meeting gathers
location_info
Any extra information associated with the meeting
location_street
The street address of the meeting
location_city_subsection
The borough (or “Ku,” if you are in Tokyo) of the city
location_neighborhood
The neighborhood of the city (like “Harlem” or “Brookline”)
location_municipality
The name of the town
location_sub_province
The county
location_province
The state or province
location_postal_code_1
The zip code, or postal code
location_nation
The nation
comments
Any comments associated with the meeting
train_lines
Any train line information associated with the meeting
bus_lines
Any bus line information associated with the meeting

Getting the Formats Used In A Search (JSON and XML Only)

The JSON and XML responses have the ability to attach an extra field to the response. This would contain the same format “legend” as returned by the switcher=GetFormats parameter, but with a key difference: These would only be the formats actually used in the meetings that were returned by the search. The switcher=GetFormats parameter returns ALL possible formats, including ones that are not used by any meetings.

get_used_formats
This appends a <formats> XML element, or a "formats": JSON element to the end of the returned search. This will contain the same data as the switcher=GetFormats parameter.
get_formats_only
This is the same as above, but it does not include any meeting data; just formats.

In the next page, we’ll cover getting change records semantically.