API Reference

Place Reference API

Overview

The Places API provides powerful search capabilities for finding and filtering places within the Motionworks database. This API supports complex queries with multiple filters, pagination, sorting, and field selection to help you locate specific venues, businesses, and points of interest.

⚠️ Under Active Development
This API endpoint is currently under active development. Features, parameters, and response formats may change without notice. Please contact your account representative for the latest updates and production readiness status.

Endpoints

Places Search

/msearch

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

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

Limitations

  • Result Limit: Maximum 10,000 total results due to search engine pagination limits
  • 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

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"
}