Places Search

Endpoint

POST /msearch

Search and filter places using multiple criteria with support for pagination, sorting, and custom field selection.

Limitations

Rate Limit: Maximum: 20 API requests per minute per API Key
Automatic Exclusions:
- Place type ID 166 (Face) is automatically excluded from all results
- Places with year 2010 and is_active: false are automatically excluded
Search Performance: Complex queries with multiple filters may have longer response times

Caching Policy

Allowed to Cache

Place IDs returned by the API may be cached and stored indefinitely for future lookup.

Not Allowed to Cache

Any other data, including but not limited to:

Place names
Coordinates (latitude/longitude)
Categories
Descriptions
Metadata
Search results

Must not be cached, stored, or indexed — even temporarily — unless explicitly authorized in writing. This includes server-side or client-side caching, database storage, or storing data in memory beyond the immediate session.

Type

POST

Request Parameters

The request body should be a JSON object containing the search criteria and configuration options.

Request Structure:

Required
- filter: Object containing search criteria and filters
Optional
- pagination: Object with page and page_size settings (default: {page: 1, page_size: 50})
- sort: Object with active field and direction (default: {active: "place_name", direction: "asc"})
- fieldSet: Array of specific fields to return in response (default: returns all standard fields)

Filter Options:

The filter object supports the following search criteria:

place_name: String - Search by place name (supports fuzzy matching)
place_ids: Array - Filter by specific place IDs
place_type_ids: Object - Filter by place type IDs with include/exclude option
audit_status: Array - Filter by audit status codes
address: String - Search by address (wildcard matching)
city: String - Filter by city name
state: String - Filter by state
zip_code: String - Filter by ZIP code
dma_name: String - Filter by DMA (Designated Market Area)

Pagination Options:

page: Number - Page number (1-based, default: 1)
page_size: Number - Number of results per page (default: 50, max results: 10,000 total)

Sorting Options:

active: String - Field to sort by (default: "place_name")
direction: String - Sort direction "asc" or "desc" (default: "asc")

Available sort fields: place_name, street_address, city, state, zip_code

Response

200 OK: Successfully retrieved search results
400 Bad Request: Issue with input parameters or search failure

The response contains a JSON object with search results and metadata.

Example Request - Basic Place Name Search

curl --location 'https://intermx-test.apigee.net/v1/msearch' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{
    "filter": {
        "place_name": "Starbucks"
    }
}'

Example Request - Geographic Search with Pagination

curl --location 'https://intermx-test.apigee.net/v1/msearch' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{
    "filter": {
        "city": "Los Angeles",
        "state": "CA"
    },
    "pagination": {
        "page": 2,
        "page_size": 25
    },
    "sort": {
        "active": "place_name",
        "direction": "asc"
    }
}'

Example Request - Complex Multi-Filter Search

curl --location 'https://intermx-test.apigee.net/v1/msearch' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{
    "filter": {
        "place_name": "Pizza",
        "city": "Chicago",
        "place_type_ids": {
            "value": ["201", "202"],
            "exclude": false
        },
        "audit_status": [3]
    },
    "pagination": {
        "page": 1,
        "page_size": 10
    },
    "sort": {
        "active": "city",
        "direction": "desc"
    },
    "fieldSet": [
        "place_name",
        "street_address", 
        "city",
        "state",
        "zip_code",
        "place_type_name"
    ]
}'

Example Request - Search by Specific Place IDs

curl --location 'https://intermx-test.apigee.net/v1/msearch' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{
    "filter": {
        "place_ids": ["318105", "318107", "318108"]
    },
    "sort": {
        "active": "place_name",
        "direction": "asc"
    }
}'

Example Request - Address and ZIP Code Search

curl --location 'https://intermx-test.apigee.net/v1/msearch' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{
    "filter": {
        "address": "Broadway",
        "zip_code": "10001"
    },
    "pagination": {
        "page": 1,
        "page_size": 20
    }
}'

Example Request - Exclude Place Types

curl --location 'https://intermx-test.apigee.net/v1/msearch' \
--header 'Content-Type: application/json' \
--header 'apikey: {YOUR API KEY HERE}' \
--data '{
    "filter": {
        "place_name": "Coffee",
        "place_type_ids": {
            "value": ["166"],
            "exclude": true
        }
    }
}'

Example Response

{
    "status": "success",
    "data": {
        "results": [
            {
                "place_id": "318105",
                "place_name": "Starbucks Coffee",
                "place_type_name": "Coffee Shop",
                "place_type_id": "201",
                "street_address": "123 Main Street",
                "city": "New York",
                "state": "NY",
                "zip_code": "10001",
                "dma_id": "501",
                "dma_name": "New York, NY",
                "audit_status": 3,
                "audit_status_cd": "Reviewed",
                "create_ts": "2024-01-15T10:30:00Z",
                "update_ts": "2024-03-20T14:45:00Z",
                "motionworks_place_id": "67ff2de13334487acdfa4971",
                "provider": "Motionworks",
                "year": 2024
            }
        ],
        "pagination": {
            "page": 1,
            "page_size": 50,
            "total_results": 1,
            "total_pages": 1
        }
    }
}

Default Field Set

When no fieldSet is specified in the request, the following fields are returned by default:

place_name - Name of the place
place_type_name - Category/type of the place
place_id - Unique identifier for the place
place_type_id - Identifier for the place category
audit_status - Numeric audit status code
audit_status_cd - Human-readable audit status
street_address - Street address of the place
city - City name
state - State name
zip_code - ZIP/postal code
dma_id - Designated Market Area identifier
dma_name - DMA name for media planning
motionworks_place_id - Motionworks internal identifier
provider - Data source provider
year - Data vintage year
Additional metadata fields including timestamps and user information

Error Handling

The API returns appropriate HTTP status codes and error messages:

200 OK: Successful search with results
400 Bad Request: Invalid request parameters, malformed JSON, or search failures

Common error scenarios include:

Missing or invalid filter criteria
Search service connection issues
Invalid pagination parameters (negative page numbers, excessive page_size)
Malformed request body or invalid JSON structure

Example error response:

{
    "status": "error", 
    "message": "Invalid pagination parameters: page must be greater than 0"
}