> ## Documentation Index > Fetch the complete documentation index at: https://docs.amazonomics.com/llms.txt > Use this file to discover all available pages before exploring further. # Search keyword rankings ## OpenAPI ````yaml /api-reference/openapi.json get /v1/search/keywords openapi: 3.0.0 info: title: Amazonomics API version: 0.0.1 description: The Amazonomics REST API. All endpoints need an API key. servers: - url: https://api.amazonomics.com security: - bearerAuth: [] paths: /v1/search/keywords: get: tags: - Search summary: Search keyword rankings parameters: - schema: anyOf: - type: string minLength: 1 - type: array items: type: string minLength: 1 minItems: 1 description: Search query - one or more keywords to search for example: laptop required: true description: Search query - one or more keywords to search for name: query in: query - schema: type: string enum: - exact - similar description: Search method to use example: similar required: false description: Search method to use name: method in: query - schema: anyOf: - type: string - type: array items: type: string description: >- Negative keyword query to exclude from similar/full-text keyword searches. Ignored for exact searches. example: decaf required: false description: >- Negative keyword query to exclude from similar/full-text keyword searches. Ignored for exact searches. name: exclude_query in: query - schema: type: string enum: - weekly - monthly description: Data frequency type example: monthly required: false description: Data frequency type name: type in: query - schema: type: integer minimum: 1 description: Page number for pagination example: 1 required: false description: Page number for pagination name: page in: query - schema: type: integer minimum: 1 maximum: 1000 description: Number of results per page (max 1000) example: 50 required: false description: Number of results per page (max 1000) name: limit in: query - schema: anyOf: - type: string - type: array items: type: string description: Filter by brand name(s) required: false description: Filter by brand name(s) name: brand in: query - schema: anyOf: - type: string - type: array items: type: string description: Filter by product ASIN(s) required: false description: Filter by product ASIN(s) name: product in: query - schema: anyOf: - type: string - type: array items: type: string description: >- Filter by friendly category bucket name(s). Known stored category names are also accepted; unmatched values are treated as Other. required: false description: >- Filter by friendly category bucket name(s). Known stored category names are also accepted; unmatched values are treated as Other. name: category in: query - schema: anyOf: - type: string enum: - latest_period - latest_rank - best_rank - worst_rank - avg_rank - total_periods - fts_rank - similarity_score - best_match - type: string pattern: ^[0-9]{1,3}-[0-9]{4}$ description: Field to sort results by, or a period (MM-YYYY/WW-YYYY) example: latest_period required: false description: Field to sort results by, or a period (MM-YYYY/WW-YYYY) name: order_by in: query - schema: type: string enum: - asc - desc - ASC - DESC description: Sort direction example: DESC required: false description: Sort direction name: order_direction in: query - schema: anyOf: - type: boolean - type: string enum: - 'true' - type: string enum: - 'false' description: Exclude results with null values in the latest period example: false required: false description: Exclude results with null values in the latest period name: exclude_nulls in: query - schema: type: string enum: - raw - delta - percentage description: Value format for period columns in exports example: raw required: false description: Value format for period columns in exports name: format in: query - schema: type: integer nullable: true minimum: 0 maximum: 50 description: >- Percentage threshold for color coding (0-50). Changes below this threshold show as neutral. example: 20 required: false description: >- Percentage threshold for color coding (0-50). Changes below this threshold show as neutral. name: color_threshold in: query responses: '200': description: Search completed successfully. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/SearchErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' components: schemas: SearchResponse: type: object properties: data: type: array nullable: true items: $ref: '#/components/schemas/SearchResult' pagination: $ref: '#/components/schemas/SearchPagination' error: type: object nullable: true properties: code: type: string description: The error code message: type: string description: The error message hint: type: string description: A hint to help the user fix the error docs: type: string description: A link to the documentation for the error required: - code - message required: - data - pagination SearchErrorResponse: type: object properties: data: nullable: true error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - data - error SearchResult: type: object properties: search_term: type: string normalized_search_term: type: string data: type: object additionalProperties: type: number summary: $ref: '#/components/schemas/SearchSummary' latest_data: $ref: '#/components/schemas/SearchLatestData' required: - search_term - normalized_search_term - data - summary - latest_data SearchPagination: type: object properties: current_page: type: number minimum: 1 page_size: type: number minimum: 1 total_count: type: number total_pages: type: number has_next: type: boolean has_previous: type: boolean required: - current_page - page_size - total_count - total_pages - has_next - has_previous SearchSummary: type: object properties: total_periods: type: number best_rank: type: number worst_rank: type: number avg_rank: type: number latest_rank: type: number latest_period: type: string required: - total_periods - best_rank - worst_rank - avg_rank - latest_rank - latest_period SearchLatestData: type: object properties: brands: type: array items: type: string products: type: array items: $ref: '#/components/schemas/SearchProduct' categories: type: array items: type: string required: - brands - products - categories SearchProduct: type: object properties: asin: type: string title: type: string click_share: type: number conversion_share: type: number required: - asin - title - click_share - conversion_share securitySchemes: bearerAuth: type: http scheme: bearer ````