openapi: 3.0.0 info: title: Meta Ad Library Page Search API description: | Search for Facebook and Instagram pages, locations, and keyword suggestions in the Meta Ad Library using a keyword. **Cross-linking**: The `page_id` from `page_results` and the `id` from `location_results` returned by this API can be used with the Meta Ad Library API to retrieve the ads associated with them. The Meta Ad Library Page Info API accepts the `page_id` to fetch page details, and the Meta Ad Library Ad Details API fetches details for a single ad. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Meta Ad Library Page Search security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Search engine to query schema: type: string enum: ["meta_ad_library_page_search"] - name: q in: query required: true description: Keyword to search for pages, locations, and keyword suggestions schema: type: string minLength: 1 - name: country in: query required: false description: Country to scope the search to (ISO 3166-1 alpha-2 country code) schema: type: string default: "ALL" enum: ["ALL", "US", "CA", "GB", "AR", "AU", "AT", "BE", "BR", "CL", "CN", "CO", "HR", "DK", "DO", "EG", "FI", "FR", "DE", "GR", "HK", "IN", "ID", "IE", "IL", "IT", "JP", "JO", "KW", "LB", "MY", "MX", "NL", "NZ", "NG", "NO", "PK", "PA", "PE", "PH", "PL", "RU", "SA", "RS", "SG", "ZA", "KR", "ES", "SE", "CH", "TW", "TH", "TR", "AE", "VE", "PT", "LU", "BG", "CZ", "SI", "IS", "SK", "LT", "TT", "BD", "LK", "KE", "HU", "MA", "CY", "JM", "EC", "RO", "BO", "GT", "CR", "QA", "SV", "HN", "NI", "PY", "UY", "PR", "BA", "PS", "TN", "BH", "VN", "GH", "MU", "UA", "MT", "BS", "MV", "OM", "MK", "LV", "EE", "IQ", "DZ", "AL", "NP", "MO", "ME", "SN", "GE", "BN", "UG", "GP", "BB", "AZ", "TZ", "LY", "MQ", "CM", "BW", "ET", "KZ", "NA", "MG", "NC", "MD", "FJ", "BY", "JE", "GU", "YE", "ZM", "IM", "HT", "KH", "AW", "PF", "AF", "BM", "GY", "AM", "MW", "AG", "RW", "GG", "GM", "FO", "LC", "KY", "BJ", "AD", "GD", "VI", "BZ", "VC", "MN", "MZ", "ML", "AO", "GF", "UZ", "DJ", "BF", "MC", "TG", "GL", "GA", "GI", "CD", "KG", "PG", "BT", "KN", "SZ", "LS", "LA", "LI", "MP", "SR", "SC", "VG", "TC", "DM", "MR", "AX", "SM", "SL", "NE", "CG", "AI", "YT", "CV", "GN", "TM", "BI", "TJ", "VU", "SB", "ER", "WS", "AS", "FK", "GQ", "TO", "KM", "PW", "FM", "CF", "SO", "MH", "VA", "TD", "KI", "ST", "TV", "NR", "RE", "LR", "ZW", "CI", "MM", "AN", "AQ", "BQ", "BV", "IO", "CX", "CC", "CK", "CW", "TF", "GW", "HM", "XK", "MS", "NU", "NF", "PN", "BL", "SH", "MF", "PM", "SX", "GS", "SS", "SJ", "TL", "TK", "UM", "WF", "EH"] - name: ad_type in: query required: false description: Type of ads to search within. Availability depends on the selected country. schema: type: string default: "all" enum: ["all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads"] responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' keyword_results: type: array description: Keyword suggestions related to the search query items: type: string page_results: type: array description: Pages matching the search query items: $ref: '#/components/schemas/PageResult' location_results: type: array description: Countries, regions, or cities associated with the search query items: $ref: '#/components/schemas/LocationResult' error: type: string description: Error message when no results are found SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Meta Ad Library URL for this search html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: Search engine used q: type: string description: Keyword used for the search country: type: string description: Country the search was scoped to ad_type: type: string description: Type of ads searched within PageResult: type: object required: [page_id, name] properties: page_id: type: string description: Unique identifier of the page. Can be used as the `page_id` parameter in the Meta Ad Library and Meta Ad Library Page Info APIs. name: type: string description: Name of the page category: type: string description: Category of the page image_uri: type: string description: URL of the page profile image likes: type: integer description: Number of likes the page has verification: type: string description: Facebook verification status of the page country: type: string description: Country associated with the page entity_type: type: string description: Type of the entity behind the page ig_username: type: string description: Instagram username linked to the page ig_followers: type: integer description: Number of Instagram followers ig_verification: type: boolean description: Whether the linked Instagram account is verified page_alias: type: string description: Alias of the page used in its URL page_is_deleted: type: boolean description: Whether the page has been deleted LocationResult: type: object required: [id, name] properties: id: type: string description: Unique identifier of the location. Can be used with the Meta Ad Library API for location-specific ad filtering. name: type: string description: Name of the location location_type: type: string description: Type of the location enum: ["COUNTRY", "REGION", "CITY"] image_uri: type: string description: URL of the location image ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong