catalog.api.docs package

Submodules

catalog.api.docs.audio_docs module

class catalog.api.docs.audio_docs.AudioComplain

Bases: MediaComplain

code_examples = [{'lang': 'Bash', 'source': '\n# Report an issue about audio ID 8624ba61-57f1-4f98-8a85-ece206c319cf\ncurl \\\n  -X POST \\\n  -H "Content-Type: application/json" \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  -d \'{"reason": "mature", "description": "This audio contains sensitive content"}\' \\\n  "https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/report/"\n'}]

desc = '\naudio_report_create is an API endpoint to report an issue about a specified audio ID to\nOpenverse.\n\nBy using this endpoint, you can report an audio file if it infringes copyright, contains\nmature or sensitive content and others.\n\n\nBy using this endpoint, you can report a file if it infringes copyright, contains mature\nor sensitive content and others.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'201': {'description': 'OK', 'examples': {'application/json': {'description': 'This audio contains sensitive content', 'identifier': '8624ba61-57f1-4f98-8a85-ece206c319cf', 'reason': 'mature'}}, 'schema': <class 'catalog.api.serializers.audio_serializers.AudioReportRequestSerializer'>}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Report an issue about audio ID 8624ba61-57f1-4f98-8a85-ece206c319cf\ncurl \\\n  -X POST \\\n  -H "Content-Type: application/json" \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  -d \'{"reason": "mature", "description": "This audio contains sensitive content"}\' \\\n  "https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/report/"\n'}], 'operation_description': '\naudio_report_create is an API endpoint to report an issue about a specified audio ID to\nOpenverse.\n\nBy using this endpoint, you can report an audio file if it infringes copyright, contains\nmature or sensitive content and others.\n\n\nBy using this endpoint, you can report a file if it infringes copyright, contains mature\nor sensitive content and others.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'audio_report', 'responses': {'201': {'description': 'OK', 'examples': {'application/json': {'description': 'This audio contains sensitive content', 'identifier': '8624ba61-57f1-4f98-8a85-ece206c319cf', 'reason': 'mature'}}, 'schema': <class 'catalog.api.serializers.audio_serializers.AudioReportRequestSerializer'>}}}

class catalog.api.docs.audio_docs.AudioDetail

Bases: MediaDetail

code_examples = [{'lang': 'Bash', 'source': '\n# Get the details of audio ID 8624ba61-57f1-4f98-8a85-ece206c319cf\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/"\n'}]

desc = '\naudio_detail is an API endpoint to get the details of a specified audio ID.\n\nBy using this endpoint, you can get audio details such as\n`id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `genres`, `filesize`, `filetype`, `tags`, `alt_files`, `attribution`, `fields_matched`, `mature`, `audio_set`, `duration`, `bit_rate`, `sample_rate`, `thumbnail`, `detail_url`, `related_url`, `waveform` and `peaks`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'200': {'description': 'OK', 'examples': {'application/json': {'alt_files': None, 'attribution': '"Wish You Were Here" by The.madpix.project is licensed under CC BY-NC-SA 3.0. To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-sa/3.0/.', 'audio_set': {'creator': 'The.madpix.project', 'creator_url': 'https://www.jamendo.com/artist/441585/the.madpix.project', 'filesize': None, 'filetype': None, 'foreign_landing_url': 'https://www.jamendo.com/album/145774/wish-you-were-here', 'title': 'Wish You Were Here', 'url': 'https://usercontent.jamendo.com?type=album&id=145774&width=200'}, 'bit_rate': 128000, 'category': 'music', 'creator': 'The.madpix.project', 'creator_url': 'https://www.jamendo.com/artist/441585/the.madpix.project', 'detail_url': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/', 'duration': 270000, 'fields_matched': [], 'filesize': 7139840, 'filetype': 'mp3', 'foreign_landing_url': 'https://www.jamendo.com/track/1214935', 'genres': ['dance', 'electronic', 'house'], 'id': '8624ba61-57f1-4f98-8a85-ece206c319cf', 'license': 'by-nc-sa', 'license_url': 'https://creativecommons.org/licenses/by-nc-sa/3.0/', 'license_version': '3.0', 'mature': False, 'provider': 'jamendo', 'related_url': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/related/', 'sample_rate': 44100, 'source': 'jamendo', 'tags': [{'accuracy': None, 'name': 'vocal'}, {'accuracy': None, 'name': 'female'}, {'accuracy': None, 'name': 'speed_medium'}, {'accuracy': None, 'name': 'guitar'}, {'accuracy': None, 'name': 'strings'}, {'accuracy': None, 'name': 'energetic'}, {'accuracy': None, 'name': 'acoustic'}, {'accuracy': None, 'name': 'vocal'}, {'accuracy': None, 'name': 'voice'}, {'accuracy': None, 'name': 'funkyhouse'}], 'thumbnail': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/thumb/', 'title': 'Wish You Were Here', 'url': 'https://mp3d.jamendo.com/download/track/1214935/mp32', 'waveform': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/waveform/'}}, 'schema': <class 'catalog.api.serializers.audio_serializers.AudioSerializer'>}, '404': {'description': 'OK', 'examples': {'application/json': {'detail': 'Not found.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Get the details of audio ID 8624ba61-57f1-4f98-8a85-ece206c319cf\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/"\n'}], 'operation_description': '\naudio_detail is an API endpoint to get the details of a specified audio ID.\n\nBy using this endpoint, you can get audio details such as\n`id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `genres`, `filesize`, `filetype`, `tags`, `alt_files`, `attribution`, `fields_matched`, `mature`, `audio_set`, `duration`, `bit_rate`, `sample_rate`, `thumbnail`, `detail_url`, `related_url`, `waveform` and `peaks`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'audio_detail', 'responses': {'200': {'description': 'OK', 'examples': {'application/json': {'alt_files': None, 'attribution': '"Wish You Were Here" by The.madpix.project is licensed under CC BY-NC-SA 3.0. To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-sa/3.0/.', 'audio_set': {'creator': 'The.madpix.project', 'creator_url': 'https://www.jamendo.com/artist/441585/the.madpix.project', 'filesize': None, 'filetype': None, 'foreign_landing_url': 'https://www.jamendo.com/album/145774/wish-you-were-here', 'title': 'Wish You Were Here', 'url': 'https://usercontent.jamendo.com?type=album&id=145774&width=200'}, 'bit_rate': 128000, 'category': 'music', 'creator': 'The.madpix.project', 'creator_url': 'https://www.jamendo.com/artist/441585/the.madpix.project', 'detail_url': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/', 'duration': 270000, 'fields_matched': [], 'filesize': 7139840, 'filetype': 'mp3', 'foreign_landing_url': 'https://www.jamendo.com/track/1214935', 'genres': ['dance', 'electronic', 'house'], 'id': '8624ba61-57f1-4f98-8a85-ece206c319cf', 'license': 'by-nc-sa', 'license_url': 'https://creativecommons.org/licenses/by-nc-sa/3.0/', 'license_version': '3.0', 'mature': False, 'provider': 'jamendo', 'related_url': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/related/', 'sample_rate': 44100, 'source': 'jamendo', 'tags': [{'accuracy': None, 'name': 'vocal'}, {'accuracy': None, 'name': 'female'}, {'accuracy': None, 'name': 'speed_medium'}, {'accuracy': None, 'name': 'guitar'}, {'accuracy': None, 'name': 'strings'}, {'accuracy': None, 'name': 'energetic'}, {'accuracy': None, 'name': 'acoustic'}, {'accuracy': None, 'name': 'vocal'}, {'accuracy': None, 'name': 'voice'}, {'accuracy': None, 'name': 'funkyhouse'}], 'thumbnail': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/thumb/', 'title': 'Wish You Were Here', 'url': 'https://mp3d.jamendo.com/download/track/1214935/mp32', 'waveform': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/waveform/'}}, 'schema': <class 'catalog.api.serializers.audio_serializers.AudioSerializer'>}, '404': {'description': 'OK', 'examples': {'application/json': {'detail': 'Not found.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}}

class catalog.api.docs.audio_docs.AudioRelated

Bases: MediaRelated

code_examples = [{'lang': 'Bash', 'source': '\n# Get related audio files for audio ID 8624ba61-57f1-4f98-8a85-ece206c319cf\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/related/"\n'}]

desc = '\nrecommendations_audio_read is an API endpoint to get related audio files for a specified\naudio ID.\n\nBy using this endpoint, you can get the details of related audio such as\n`id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `genres`, `filesize`, `filetype`, `tags`, `alt_files`, `attribution`, `fields_matched`, `mature`, `audio_set`, `duration`, `bit_rate`, `sample_rate`, `thumbnail`, `detail_url`, `related_url`, `waveform` and `peaks`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'200': {'description': 'OK', 'examples': {'application/json': {'page_count': 1, 'result_count': 10000, 'results': [{'title': 'File:Mozart - Eine kleine Nachtmusik - 1. Allegro.ogg', 'id': '36537842-b067-4ca0-ad67-e00ff2e06b2e', 'creator': 'Wolfgang Amadeus Mozart', 'creator_url': 'https://en.wikipedia.org/wiki/Wolfgang_Amadeus_Mozart', 'url': 'https://upload.wikimedia.org/wikipedia/commons/2/24/Mozart_-_Eine_kleine_Nachtmusik_-_1._Allegro.ogg', 'provider': 'wikimedia', 'source': 'wikimedia', 'license': 'by-sa', 'license_version': '2.0', 'license_url': 'https://creativecommons.org/licenses/by-sa/2.0/', 'foreign_landing_url': 'https://commons.wikimedia.org/w/index.php?curid=3536953', 'detail_url': 'http://api.openverse.engineering/v1/audio/36537842-b067-4ca0-ad67-e00ff2e06b2e', 'related_url': 'http://api.openverse.engineering/v1/recommendations/audio/36537842-b067-4ca0-ad67-e00ff2e06b2e', 'fields_matched': ['description', 'title'], 'tags': [{'name': 'exam'}, {'name': 'tactics'}]}]}}, 'schema': <class 'catalog.api.serializers.audio_serializers.AudioSerializer'>}, '404': {'description': 'Not Found', 'examples': {'application/json': {'detail': 'An internal server error occurred.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Get related audio files for audio ID 8624ba61-57f1-4f98-8a85-ece206c319cf\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/related/"\n'}], 'operation_description': '\nrecommendations_audio_read is an API endpoint to get related audio files for a specified\naudio ID.\n\nBy using this endpoint, you can get the details of related audio such as\n`id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `genres`, `filesize`, `filetype`, `tags`, `alt_files`, `attribution`, `fields_matched`, `mature`, `audio_set`, `duration`, `bit_rate`, `sample_rate`, `thumbnail`, `detail_url`, `related_url`, `waveform` and `peaks`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'audio_related', 'responses': {'200': {'description': 'OK', 'examples': {'application/json': {'page_count': 1, 'result_count': 10000, 'results': [{'title': 'File:Mozart - Eine kleine Nachtmusik - 1. Allegro.ogg', 'id': '36537842-b067-4ca0-ad67-e00ff2e06b2e', 'creator': 'Wolfgang Amadeus Mozart', 'creator_url': 'https://en.wikipedia.org/wiki/Wolfgang_Amadeus_Mozart', 'url': 'https://upload.wikimedia.org/wikipedia/commons/2/24/Mozart_-_Eine_kleine_Nachtmusik_-_1._Allegro.ogg', 'provider': 'wikimedia', 'source': 'wikimedia', 'license': 'by-sa', 'license_version': '2.0', 'license_url': 'https://creativecommons.org/licenses/by-sa/2.0/', 'foreign_landing_url': 'https://commons.wikimedia.org/w/index.php?curid=3536953', 'detail_url': 'http://api.openverse.engineering/v1/audio/36537842-b067-4ca0-ad67-e00ff2e06b2e', 'related_url': 'http://api.openverse.engineering/v1/recommendations/audio/36537842-b067-4ca0-ad67-e00ff2e06b2e', 'fields_matched': ['description', 'title'], 'tags': [{'name': 'exam'}, {'name': 'tactics'}]}]}}, 'schema': <class 'catalog.api.serializers.audio_serializers.AudioSerializer'>}, '404': {'description': 'Not Found', 'examples': {'application/json': {'detail': 'An internal server error occurred.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}}

class catalog.api.docs.audio_docs.AudioSearch

Bases: MediaSearch

code_examples = [{'lang': 'Bash', 'source': '\n# Example 0: Search for audio using single query parameter\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=test"\n\n\n# Example 1: Search for audio using multiple query parameters\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=test&license=pdm,by&categories=illustration&page_size=1&page=1"\n\n\n# Example 2: Search for audio that is an exact match of Giacomo Puccini\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=%22Giacomo%20Puccini%22"\n\n\n# Example 3: Search for audio related to both dog and cat\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=dog+cat"\n\n\n# Example 4: Search for audio related to dog or cat, but not necessarily both\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=dog|cat"\n\n\n# Example 5: Search for audio related to dog but won\'t include results related to \'pug\'\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=dog -pug"\n\n\n# Example 6: Search for audio matching anything with the prefix \'net\'\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=net*"\n\n\n# Example 7: Search for audio matching dogs that are either corgis or labrador\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=dogs + (corgis | labrador)"\n\n\n# Example 8: Search for audio matching strings close to the term theater with a difference of one character\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=theatre~1"\n'}]

desc = '\naudio_search is an API endpoint to search audio files using a query string.\n\nBy using this endpoint, you can obtain search results based on specified query and\noptionally filter results by\n`q`, `license`, `license_type`, `creator`, `tags`, `title`, `filter_dead`, `extension`, `mature`, `qa`, `page_size`, `page`, `source`, `excluded_source`, `category` and `length`.\n\n\nResults are ranked in order of relevance and paginated on the basis of the `page` param.\nThe `page_size` param controls the total number of pages.\n\nAlthough there may be millions of relevant records, only the most relevant several\nthousand records can be viewed. This is by design: the search endpoint should be used to\nfind the top 10,000 most relevant results, not for exhaustive search or bulk download of\nevery barely relevant result. As such, the caller should not try to access pages beyond\n`page_count`, or else the server will reject the query.\n\nFor more precise results, you can go to the\n[Openverse Syntax Guide](https://search.creativecommons.org/search-help)\nfor information about creating queries and\n[Apache Lucene Syntax Guide](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html)\nfor information on structuring advanced searches.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'200': {'description': 'OK', 'examples': {'application/json': {'page': 1, 'page_count': 1, 'page_size': 20, 'result_count': 1, 'results': [{'id': '8624ba61-57f1-4f98-8a85-ece206c319cf', 'title': 'Wish You Were Here', 'foreign_landing_url': 'https://www.jamendo.com/track/1214935', 'url': 'https://mp3d.jamendo.com/download/track/1214935/mp32', 'creator': 'The.madpix.project', 'creator_url': 'https://www.jamendo.com/artist/441585/the.madpix.project', 'license': 'by-nc-sa', 'license_version': '3.0', 'license_url': 'https://creativecommons.org/licenses/by-nc-sa/3.0/', 'provider': 'jamendo', 'source': 'jamendo', 'category': 'music', 'genres': ['dance', 'electronic', 'house'], 'filesize': 7139840, 'filetype': 'mp3', 'tags': [{'accuracy': None, 'name': 'vocal'}, {'accuracy': None, 'name': 'female'}, {'accuracy': None, 'name': 'speed_medium'}, {'accuracy': None, 'name': 'guitar'}, {'accuracy': None, 'name': 'strings'}, {'accuracy': None, 'name': 'energetic'}, {'accuracy': None, 'name': 'acoustic'}, {'accuracy': None, 'name': 'vocal'}, {'accuracy': None, 'name': 'voice'}, {'accuracy': None, 'name': 'funkyhouse'}], 'alt_files': None, 'attribution': '"Wish You Were Here" by The.madpix.project is licensed under CC BY-NC-SA 3.0. To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-sa/3.0/.', 'fields_matched': ['title'], 'mature': False, 'audio_set': {'title': 'Wish You Were Here', 'foreign_landing_url': 'https://www.jamendo.com/album/145774/wish-you-were-here', 'creator': 'The.madpix.project', 'creator_url': 'https://www.jamendo.com/artist/441585/the.madpix.project', 'url': 'https://usercontent.jamendo.com?type=album&id=145774&width=200', 'filesize': None, 'filetype': None}, 'duration': 270000, 'bit_rate': 128000, 'sample_rate': 44100, 'thumbnail': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/thumb/', 'detail_url': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/', 'related_url': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/related/', 'waveform': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/waveform/'}]}}, 'schema': AudioSearchSerializer(many=True):     result_count = IntegerField(help_text='The total number of items returned by search result.')     page_count = IntegerField(help_text='The total number of pages returned by search result.')     page_size = IntegerField(help_text='The number of items per page.')     page = IntegerField(help_text='The current page number returned in the response.')     results = AudioSerializer(help_text='An array of audios and their details such as `id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `genres`, `filesize`, `filetype`, `tags`, `alt_files`, `attribution`, `fields_matched`, `mature`, `audio_set`, `duration`, `bit_rate`, `sample_rate`, `thumbnail`, `detail_url`, `related_url`, `waveform` and `peaks`.', many=True):         id = CharField(help_text='Our unique identifier for an open-licensed work.', source='identifier')         title = CharField(allow_blank=True, allow_null=True, help_text='The name of the media.', max_length=2000, required=False)         foreign_landing_url = CharField(allow_blank=True, allow_null=True, help_text='The landing page of the work.', max_length=1000, required=False)         url = URLField(allow_blank=True, allow_null=True, help_text='The actual URL to the media file.', max_length=1000, required=False, validators=[<UniqueValidator(queryset=Audio.objects.all())>])         creator = CharField(allow_blank=True, allow_null=True, help_text='The name of the media creator.', max_length=2000, required=False)         creator_url = URLField(allow_blank=True, allow_null=True, help_text='A direct link to the media creator.', max_length=2000, required=False)         license = CharField(help_text='The name of license for the media.', max_length=50)         license_version = CharField(allow_blank=True, allow_null=True, help_text='The version of the media license.', max_length=25, required=False)         license_url = ReadOnlyField(allow_null=True, help_text='A direct link to the license deed or legal terms.')         provider = CharField(allow_blank=True, allow_null=True, help_text='The content provider, e.g. Flickr, Jamendo...', max_length=80, required=False)         source = CharField(allow_blank=True, allow_null=True, help_text='The source of the data, meaning a particular dataset. Source and provider can be different. Eg: the Google Open Images dataset is source=openimages, but provider=flickr.', max_length=80, required=False)         category = CharField(allow_blank=True, allow_null=True, help_text='The top-level classification of this media file.', max_length=80, required=False)         genres = ListField(allow_empty=False, allow_null=True, child=CharField(allow_blank=True, label='Genres', max_length=80, required=False), help_text='An array of audio genres such as `rock`, `electronic` for `music` category, or `politics`, `sport`, `education` for `podcast` category', required=False)         filesize = IntegerField(allow_null=True, help_text='Number in bytes, e.g. 1024.', max_value=2147483647, min_value=-2147483648, required=False)         filetype = CharField(allow_blank=True, allow_null=True, help_text='The type of the file, related to the file extension.', max_length=80, required=False)         tags = TagSerializer(allow_null=True, help_text='Tags with detailed metadata, such as accuracy.', many=True):             name = CharField(help_text='The name of a detailed tag.')             accuracy = FloatField(default=None, help_text='The accuracy of a machine-generated tag. Human-generated tags have a null accuracy field.')         alt_files = JSONField(allow_null=True, decoder=None, encoder=None, help_text='JSON describing alternative files for this audio.', required=False, style={'base_template': 'textarea.html'})         attribution = ReadOnlyField(allow_null=True, help_text='\n        The plain-text English attribution for a media item.\n\n        Use this to credit creators for their work and fulfill legal attribution\n        requirements.\n        ')         fields_matched = ListField(allow_null=True, help_text='List the fields that matched the query for this result.')         mature = BooleanField(help_text='Whether the media item is marked as mature')         audio_set = AudioSetSerializer(allow_null=True, help_text='Reference to set of which this track is a part.', read_only=True):             title = CharField(allow_blank=True, allow_null=True, help_text='The name of the media.', max_length=2000, required=False)             foreign_landing_url = CharField(allow_blank=True, allow_null=True, help_text='The landing page of the work.', max_length=1000, required=False)             creator = CharField(allow_blank=True, allow_null=True, help_text='The name of the media creator.', max_length=2000, required=False)             creator_url = URLField(allow_blank=True, allow_null=True, help_text='A direct link to the media creator.', max_length=2000, required=False)             url = URLField(allow_blank=True, allow_null=True, help_text='The actual URL to the media file.', max_length=1000, required=False, validators=[<UniqueValidator(queryset=AudioSet.objects.all())>])             filesize = IntegerField(allow_null=True, help_text='Number in bytes, e.g. 1024.', max_value=2147483647, min_value=-2147483648, required=False)             filetype = CharField(allow_blank=True, allow_null=True, help_text='The type of the file, related to the file extension.', max_length=80, required=False)         duration = IntegerField(allow_null=True, help_text='The time length of the audio file in milliseconds.', max_value=2147483647, min_value=-2147483648, required=False)         bit_rate = IntegerField(allow_null=True, help_text='Number in bits per second, eg. 128000.', max_value=2147483647, min_value=-2147483648, required=False)         sample_rate = IntegerField(allow_null=True, help_text='Number in hertz, eg. 44100.', max_value=2147483647, min_value=-2147483648, required=False)         thumbnail = SchemableHyperlinkedIdentityField(help_text='A direct link to the miniature artwork.', lookup_field='identifier', read_only=True, view_name='audio-thumb')         detail_url = SchemableHyperlinkedIdentityField(help_text='A direct link to the detail view of this audio file.', lookup_field='identifier', read_only=True, view_name='audio-detail')         related_url = SchemableHyperlinkedIdentityField(help_text='A link to an endpoint that provides similar audio files.', lookup_field='identifier', read_only=True, view_name='audio-related')         waveform = SchemableHyperlinkedIdentityField(help_text='A direct link to the waveform peaks.', lookup_field='identifier', read_only=True, view_name='audio-waveform')}, '400': {'description': 'Bad Request', 'examples': {'application/json': {'detail': "Invalid input given for fields. 'license' -> License 'PDMNBCG' does not exist.", 'error': 'InputError', 'fields': ['license']}}, 'schema': <class 'catalog.api.serializers.error_serializers.InputErrorSerializer'>}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Example 0: Search for audio using single query parameter\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=test"\n\n\n# Example 1: Search for audio using multiple query parameters\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=test&license=pdm,by&categories=illustration&page_size=1&page=1"\n\n\n# Example 2: Search for audio that is an exact match of Giacomo Puccini\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=%22Giacomo%20Puccini%22"\n\n\n# Example 3: Search for audio related to both dog and cat\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=dog+cat"\n\n\n# Example 4: Search for audio related to dog or cat, but not necessarily both\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=dog|cat"\n\n\n# Example 5: Search for audio related to dog but won\'t include results related to \'pug\'\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=dog -pug"\n\n\n# Example 6: Search for audio matching anything with the prefix \'net\'\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=net*"\n\n\n# Example 7: Search for audio matching dogs that are either corgis or labrador\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=dogs + (corgis | labrador)"\n\n\n# Example 8: Search for audio matching strings close to the term theater with a difference of one character\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/?q=theatre~1"\n'}], 'operation_description': '\naudio_search is an API endpoint to search audio files using a query string.\n\nBy using this endpoint, you can obtain search results based on specified query and\noptionally filter results by\n`q`, `license`, `license_type`, `creator`, `tags`, `title`, `filter_dead`, `extension`, `mature`, `qa`, `page_size`, `page`, `source`, `excluded_source`, `category` and `length`.\n\n\nResults are ranked in order of relevance and paginated on the basis of the `page` param.\nThe `page_size` param controls the total number of pages.\n\nAlthough there may be millions of relevant records, only the most relevant several\nthousand records can be viewed. This is by design: the search endpoint should be used to\nfind the top 10,000 most relevant results, not for exhaustive search or bulk download of\nevery barely relevant result. As such, the caller should not try to access pages beyond\n`page_count`, or else the server will reject the query.\n\nFor more precise results, you can go to the\n[Openverse Syntax Guide](https://search.creativecommons.org/search-help)\nfor information about creating queries and\n[Apache Lucene Syntax Guide](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html)\nfor information on structuring advanced searches.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'audio_search', 'query_serializer': <class 'catalog.api.serializers.audio_serializers.AudioSearchRequestSerializer'>, 'responses': {'200': {'description': 'OK', 'examples': {'application/json': {'page': 1, 'page_count': 1, 'page_size': 20, 'result_count': 1, 'results': [{'id': '8624ba61-57f1-4f98-8a85-ece206c319cf', 'title': 'Wish You Were Here', 'foreign_landing_url': 'https://www.jamendo.com/track/1214935', 'url': 'https://mp3d.jamendo.com/download/track/1214935/mp32', 'creator': 'The.madpix.project', 'creator_url': 'https://www.jamendo.com/artist/441585/the.madpix.project', 'license': 'by-nc-sa', 'license_version': '3.0', 'license_url': 'https://creativecommons.org/licenses/by-nc-sa/3.0/', 'provider': 'jamendo', 'source': 'jamendo', 'category': 'music', 'genres': ['dance', 'electronic', 'house'], 'filesize': 7139840, 'filetype': 'mp3', 'tags': [{'accuracy': None, 'name': 'vocal'}, {'accuracy': None, 'name': 'female'}, {'accuracy': None, 'name': 'speed_medium'}, {'accuracy': None, 'name': 'guitar'}, {'accuracy': None, 'name': 'strings'}, {'accuracy': None, 'name': 'energetic'}, {'accuracy': None, 'name': 'acoustic'}, {'accuracy': None, 'name': 'vocal'}, {'accuracy': None, 'name': 'voice'}, {'accuracy': None, 'name': 'funkyhouse'}], 'alt_files': None, 'attribution': '"Wish You Were Here" by The.madpix.project is licensed under CC BY-NC-SA 3.0. To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-sa/3.0/.', 'fields_matched': ['title'], 'mature': False, 'audio_set': {'title': 'Wish You Were Here', 'foreign_landing_url': 'https://www.jamendo.com/album/145774/wish-you-were-here', 'creator': 'The.madpix.project', 'creator_url': 'https://www.jamendo.com/artist/441585/the.madpix.project', 'url': 'https://usercontent.jamendo.com?type=album&id=145774&width=200', 'filesize': None, 'filetype': None}, 'duration': 270000, 'bit_rate': 128000, 'sample_rate': 44100, 'thumbnail': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/thumb/', 'detail_url': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/', 'related_url': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/related/', 'waveform': 'https://api.openverse.engineering/v1/audio/8624ba61-57f1-4f98-8a85-ece206c319cf/waveform/'}]}}, 'schema': AudioSearchSerializer(many=True):     result_count = IntegerField(help_text='The total number of items returned by search result.')     page_count = IntegerField(help_text='The total number of pages returned by search result.')     page_size = IntegerField(help_text='The number of items per page.')     page = IntegerField(help_text='The current page number returned in the response.')     results = AudioSerializer(help_text='An array of audios and their details such as `id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `genres`, `filesize`, `filetype`, `tags`, `alt_files`, `attribution`, `fields_matched`, `mature`, `audio_set`, `duration`, `bit_rate`, `sample_rate`, `thumbnail`, `detail_url`, `related_url`, `waveform` and `peaks`.', many=True):         id = CharField(help_text='Our unique identifier for an open-licensed work.', source='identifier')         title = CharField(allow_blank=True, allow_null=True, help_text='The name of the media.', max_length=2000, required=False)         foreign_landing_url = CharField(allow_blank=True, allow_null=True, help_text='The landing page of the work.', max_length=1000, required=False)         url = URLField(allow_blank=True, allow_null=True, help_text='The actual URL to the media file.', max_length=1000, required=False, validators=[<UniqueValidator(queryset=Audio.objects.all())>])         creator = CharField(allow_blank=True, allow_null=True, help_text='The name of the media creator.', max_length=2000, required=False)         creator_url = URLField(allow_blank=True, allow_null=True, help_text='A direct link to the media creator.', max_length=2000, required=False)         license = CharField(help_text='The name of license for the media.', max_length=50)         license_version = CharField(allow_blank=True, allow_null=True, help_text='The version of the media license.', max_length=25, required=False)         license_url = ReadOnlyField(allow_null=True, help_text='A direct link to the license deed or legal terms.')         provider = CharField(allow_blank=True, allow_null=True, help_text='The content provider, e.g. Flickr, Jamendo...', max_length=80, required=False)         source = CharField(allow_blank=True, allow_null=True, help_text='The source of the data, meaning a particular dataset. Source and provider can be different. Eg: the Google Open Images dataset is source=openimages, but provider=flickr.', max_length=80, required=False)         category = CharField(allow_blank=True, allow_null=True, help_text='The top-level classification of this media file.', max_length=80, required=False)         genres = ListField(allow_empty=False, allow_null=True, child=CharField(allow_blank=True, label='Genres', max_length=80, required=False), help_text='An array of audio genres such as `rock`, `electronic` for `music` category, or `politics`, `sport`, `education` for `podcast` category', required=False)         filesize = IntegerField(allow_null=True, help_text='Number in bytes, e.g. 1024.', max_value=2147483647, min_value=-2147483648, required=False)         filetype = CharField(allow_blank=True, allow_null=True, help_text='The type of the file, related to the file extension.', max_length=80, required=False)         tags = TagSerializer(allow_null=True, help_text='Tags with detailed metadata, such as accuracy.', many=True):             name = CharField(help_text='The name of a detailed tag.')             accuracy = FloatField(default=None, help_text='The accuracy of a machine-generated tag. Human-generated tags have a null accuracy field.')         alt_files = JSONField(allow_null=True, decoder=None, encoder=None, help_text='JSON describing alternative files for this audio.', required=False, style={'base_template': 'textarea.html'})         attribution = ReadOnlyField(allow_null=True, help_text='\n        The plain-text English attribution for a media item.\n\n        Use this to credit creators for their work and fulfill legal attribution\n        requirements.\n        ')         fields_matched = ListField(allow_null=True, help_text='List the fields that matched the query for this result.')         mature = BooleanField(help_text='Whether the media item is marked as mature')         audio_set = AudioSetSerializer(allow_null=True, help_text='Reference to set of which this track is a part.', read_only=True):             title = CharField(allow_blank=True, allow_null=True, help_text='The name of the media.', max_length=2000, required=False)             foreign_landing_url = CharField(allow_blank=True, allow_null=True, help_text='The landing page of the work.', max_length=1000, required=False)             creator = CharField(allow_blank=True, allow_null=True, help_text='The name of the media creator.', max_length=2000, required=False)             creator_url = URLField(allow_blank=True, allow_null=True, help_text='A direct link to the media creator.', max_length=2000, required=False)             url = URLField(allow_blank=True, allow_null=True, help_text='The actual URL to the media file.', max_length=1000, required=False, validators=[<UniqueValidator(queryset=AudioSet.objects.all())>])             filesize = IntegerField(allow_null=True, help_text='Number in bytes, e.g. 1024.', max_value=2147483647, min_value=-2147483648, required=False)             filetype = CharField(allow_blank=True, allow_null=True, help_text='The type of the file, related to the file extension.', max_length=80, required=False)         duration = IntegerField(allow_null=True, help_text='The time length of the audio file in milliseconds.', max_value=2147483647, min_value=-2147483648, required=False)         bit_rate = IntegerField(allow_null=True, help_text='Number in bits per second, eg. 128000.', max_value=2147483647, min_value=-2147483648, required=False)         sample_rate = IntegerField(allow_null=True, help_text='Number in hertz, eg. 44100.', max_value=2147483647, min_value=-2147483648, required=False)         thumbnail = SchemableHyperlinkedIdentityField(help_text='A direct link to the miniature artwork.', lookup_field='identifier', read_only=True, view_name='audio-thumb')         detail_url = SchemableHyperlinkedIdentityField(help_text='A direct link to the detail view of this audio file.', lookup_field='identifier', read_only=True, view_name='audio-detail')         related_url = SchemableHyperlinkedIdentityField(help_text='A link to an endpoint that provides similar audio files.', lookup_field='identifier', read_only=True, view_name='audio-related')         waveform = SchemableHyperlinkedIdentityField(help_text='A direct link to the waveform peaks.', lookup_field='identifier', read_only=True, view_name='audio-waveform')}, '400': {'description': 'Bad Request', 'examples': {'application/json': {'detail': "Invalid input given for fields. 'license' -> License 'PDMNBCG' does not exist.", 'error': 'InputError', 'fields': ['license']}}, 'schema': <class 'catalog.api.serializers.error_serializers.InputErrorSerializer'>}}}

class catalog.api.docs.audio_docs.AudioStats

Bases: MediaStats

code_examples = [{'lang': 'Bash', 'source': '\n# Get the statistics for audio sources\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/stats/"\n'}]

desc = '\naudio_stats is an API endpoint to get a list of all content providers and their\nrespective number of audio files in the Openverse catalog.\n\n\nYou can use this endpoint to get details about content providers such as `source_name`,\n`display_name`, and `source_url` along with a count of the number of individual items\nindexed from them.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'200': {'description': 'OK', 'examples': {'application/json': [{'source_name': 'freesound', 'display_name': 'Freesound', 'source_url': 'https://freesound.org/', 'logo_url': None, 'media_count': 828}, {'source_name': 'jamendo', 'display_name': 'Jamendo', 'source_url': 'https://www.jamendo.com', 'logo_url': None, 'media_count': 180}, {'source_name': 'wikimedia_audio', 'display_name': 'Wikimedia', 'source_url': 'https://commons.wikimedia.org', 'logo_url': None, 'media_count': 3992}]}, 'schema': ProviderSerializer(many=True):     source_name = CharField(help_text='The source of the media, e.g. flickr', source='provider_identifier')     display_name = CharField(help_text='The name of content provider, e.g. Flickr', source='provider_name')     source_url = URLField(help_text='The URL of the source, e.g. https://www.flickr.com', source='domain_name')     logo_url = ReadOnlyField(default=None, help_text='Deprecated and unused. Always `null`.')     media_count = SerializerMethodField(help_text='The number of media items indexed from the source.')}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Get the statistics for audio sources\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/audio/stats/"\n'}], 'operation_description': '\naudio_stats is an API endpoint to get a list of all content providers and their\nrespective number of audio files in the Openverse catalog.\n\n\nYou can use this endpoint to get details about content providers such as `source_name`,\n`display_name`, and `source_url` along with a count of the number of individual items\nindexed from them.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'audio_stats', 'responses': {'200': {'description': 'OK', 'examples': {'application/json': [{'source_name': 'freesound', 'display_name': 'Freesound', 'source_url': 'https://freesound.org/', 'logo_url': None, 'media_count': 828}, {'source_name': 'jamendo', 'display_name': 'Jamendo', 'source_url': 'https://www.jamendo.com', 'logo_url': None, 'media_count': 180}, {'source_name': 'wikimedia_audio', 'display_name': 'Wikimedia', 'source_url': 'https://commons.wikimedia.org', 'logo_url': None, 'media_count': 3992}]}, 'schema': ProviderSerializer(many=True):     source_name = CharField(help_text='The source of the media, e.g. flickr', source='provider_identifier')     display_name = CharField(help_text='The name of content provider, e.g. Flickr', source='provider_name')     source_url = URLField(help_text='The URL of the source, e.g. https://www.flickr.com', source='domain_name')     logo_url = ReadOnlyField(default=None, help_text='Deprecated and unused. Always `null`.')     media_count = SerializerMethodField(help_text='The number of media items indexed from the source.')}}}

class catalog.api.docs.audio_docs.AudioThumbnail

Bases: object

desc = '\nthumbnail is an API endpoint to retrieve the scaled down and compressed thumbnail\nof the artwork of an audio track or its audio set.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

swagger_setup = {'operation_description': '\nthumbnail is an API endpoint to retrieve the scaled down and compressed thumbnail\nof the artwork of an audio track or its audio set.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'audio_thumbnail', 'query_serializer': <class 'catalog.api.serializers.media_serializers.MediaThumbnailRequestSerializer'>}

catalog.api.docs.image_docs module

class catalog.api.docs.image_docs.ImageComplain

Bases: MediaComplain

code_examples = [{'lang': 'Bash', 'source': '\n# Report an issue about image ID 4bc43a04-ef46-4544-a0c1-63c63f56e276\ncurl \\\n  -X POST \\\n  -H "Content-Type: application/json" \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  -d \'{"reason": "mature", "description": "Image contains sensitive content"}\' \\\n  "https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/report/"\n'}]

desc = '\nimages_report_create is an API endpoint to report an issue about a specified image ID to\nOpenverse.\n\nBy using this endpoint, you can report an image if it infringes copyright, contains\nmature or sensitive content and others.\n\n\nBy using this endpoint, you can report a file if it infringes copyright, contains mature\nor sensitive content and others.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'201': {'description': 'OK', 'examples': {'application/json': {'description': 'Image contains sensitive content', 'identifier': '4bc43a04-ef46-4544-a0c1-63c63f56e276', 'reason': 'mature'}}, 'schema': <class 'catalog.api.serializers.image_serializers.ImageReportRequestSerializer'>}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Report an issue about image ID 4bc43a04-ef46-4544-a0c1-63c63f56e276\ncurl \\\n  -X POST \\\n  -H "Content-Type: application/json" \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  -d \'{"reason": "mature", "description": "Image contains sensitive content"}\' \\\n  "https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/report/"\n'}], 'operation_description': '\nimages_report_create is an API endpoint to report an issue about a specified image ID to\nOpenverse.\n\nBy using this endpoint, you can report an image if it infringes copyright, contains\nmature or sensitive content and others.\n\n\nBy using this endpoint, you can report a file if it infringes copyright, contains mature\nor sensitive content and others.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'image_report', 'responses': {'201': {'description': 'OK', 'examples': {'application/json': {'description': 'Image contains sensitive content', 'identifier': '4bc43a04-ef46-4544-a0c1-63c63f56e276', 'reason': 'mature'}}, 'schema': <class 'catalog.api.serializers.image_serializers.ImageReportRequestSerializer'>}}}

class catalog.api.docs.image_docs.ImageDetail

Bases: MediaDetail

code_examples = [{'lang': 'Bash', 'source': '\n# Get the details of image ID 4bc43a04-ef46-4544-a0c1-63c63f56e276\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/"\n'}]

desc = '\nimage_detail is an API endpoint to get the details of a specified image ID.\n\nBy using this endpoint, you can image details such as\n`id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `filesize`, `filetype`, `tags`, `attribution`, `fields_matched`, `mature`, `height`, `width`, `thumbnail`, `detail_url` and `related_url`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'200': {'description': 'OK', 'examples': {'application/json': {'attribution': '"Tree Bark Photo" by Tim Sullivan is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/.', 'category': 'photograph', 'creator': 'Tim Sullivan', 'creator_url': 'https://www.secretagencygroup.com', 'detail_url': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/', 'fields_matched': [], 'filesize': 896128, 'filetype': 'jpg', 'foreign_landing_url': 'https://stocksnap.io/photo/XNVBVXO3B7', 'height': 4016, 'id': '4bc43a04-ef46-4544-a0c1-63c63f56e276', 'license': 'cc0', 'license_url': 'https://creativecommons.org/publicdomain/zero/1.0/', 'license_version': '1.0', 'mature': False, 'provider': 'stocksnap', 'related_url': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/', 'source': 'stocksnap', 'tags': [{'accuracy': None, 'name': 'tree'}, {'accuracy': None, 'name': 'bark'}, {'accuracy': None, 'name': 'texture'}, {'accuracy': None, 'name': 'wood'}, {'accuracy': None, 'name': 'nature'}, {'accuracy': None, 'name': 'pattern'}, {'accuracy': None, 'name': 'rough'}, {'accuracy': None, 'name': 'surface'}, {'accuracy': None, 'name': 'brown'}, {'accuracy': None, 'name': 'old'}, {'accuracy': None, 'name': 'background'}, {'accuracy': None, 'name': 'trunk'}, {'accuracy': None, 'name': 'natural'}, {'accuracy': None, 'name': 'forest'}, {'accuracy': None, 'name': 'detail'}, {'accuracy': None, 'name': 'lumber'}, {'accuracy': None, 'name': 'weathered'}, {'accuracy': None, 'name': 'timber'}, {'accuracy': None, 'name': 'stump'}, {'accuracy': None, 'name': 'closeup'}, {'accuracy': None, 'name': 'root'}], 'thumbnail': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/thumb/', 'title': 'Tree Bark Photo', 'url': 'https://cdn.stocksnap.io/img-thumbs/960w/XNVBVXO3B7.jpg', 'width': 6016}}, 'schema': <class 'catalog.api.serializers.image_serializers.ImageSerializer'>}, '404': {'description': 'Not Found', 'examples': {'application/json': {'detail': 'Not found.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Get the details of image ID 4bc43a04-ef46-4544-a0c1-63c63f56e276\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/"\n'}], 'operation_description': '\nimage_detail is an API endpoint to get the details of a specified image ID.\n\nBy using this endpoint, you can image details such as\n`id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `filesize`, `filetype`, `tags`, `attribution`, `fields_matched`, `mature`, `height`, `width`, `thumbnail`, `detail_url` and `related_url`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'image_detail', 'responses': {'200': {'description': 'OK', 'examples': {'application/json': {'attribution': '"Tree Bark Photo" by Tim Sullivan is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/.', 'category': 'photograph', 'creator': 'Tim Sullivan', 'creator_url': 'https://www.secretagencygroup.com', 'detail_url': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/', 'fields_matched': [], 'filesize': 896128, 'filetype': 'jpg', 'foreign_landing_url': 'https://stocksnap.io/photo/XNVBVXO3B7', 'height': 4016, 'id': '4bc43a04-ef46-4544-a0c1-63c63f56e276', 'license': 'cc0', 'license_url': 'https://creativecommons.org/publicdomain/zero/1.0/', 'license_version': '1.0', 'mature': False, 'provider': 'stocksnap', 'related_url': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/', 'source': 'stocksnap', 'tags': [{'accuracy': None, 'name': 'tree'}, {'accuracy': None, 'name': 'bark'}, {'accuracy': None, 'name': 'texture'}, {'accuracy': None, 'name': 'wood'}, {'accuracy': None, 'name': 'nature'}, {'accuracy': None, 'name': 'pattern'}, {'accuracy': None, 'name': 'rough'}, {'accuracy': None, 'name': 'surface'}, {'accuracy': None, 'name': 'brown'}, {'accuracy': None, 'name': 'old'}, {'accuracy': None, 'name': 'background'}, {'accuracy': None, 'name': 'trunk'}, {'accuracy': None, 'name': 'natural'}, {'accuracy': None, 'name': 'forest'}, {'accuracy': None, 'name': 'detail'}, {'accuracy': None, 'name': 'lumber'}, {'accuracy': None, 'name': 'weathered'}, {'accuracy': None, 'name': 'timber'}, {'accuracy': None, 'name': 'stump'}, {'accuracy': None, 'name': 'closeup'}, {'accuracy': None, 'name': 'root'}], 'thumbnail': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/thumb/', 'title': 'Tree Bark Photo', 'url': 'https://cdn.stocksnap.io/img-thumbs/960w/XNVBVXO3B7.jpg', 'width': 6016}}, 'schema': <class 'catalog.api.serializers.image_serializers.ImageSerializer'>}, '404': {'description': 'Not Found', 'examples': {'application/json': {'detail': 'Not found.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}}

class catalog.api.docs.image_docs.ImageOembed

Bases: object

code_examples = [{'lang': 'Bash', 'source': '\n# Retrieve embedded content from an image\'s URL\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/oembed/?url=https://wordpress.org/openverse/photos/4bc43a04-ef46-4544-a0c1-63c63f56e276"\n'}]

desc = '\noembed_list is an API endpoint to retrieve embedded content from a specified image URL.\n\nBy using this endpoint, you can retrieve embedded content such as `version`, `type`,\n`width`, `height`, `title`, `author_name`, `author_url` and `license_url`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'200': {'description': 'OK', 'examples': {'application/json': {'author_name': 'Tim Sullivan', 'author_url': 'https://www.secretagencygroup.com', 'height': 4016, 'license_url': 'https://creativecommons.org/publicdomain/zero/1.0/', 'title': 'Tree Bark Photo', 'type': 'photo', 'version': '1.0', 'width': 6016}}, 'schema': <class 'catalog.api.serializers.image_serializers.OembedSerializer'>}, '404': {'description': 'Not Found', 'examples': {'application/json': {'detail': 'An internal server error occurred.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Retrieve embedded content from an image\'s URL\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/oembed/?url=https://wordpress.org/openverse/photos/4bc43a04-ef46-4544-a0c1-63c63f56e276"\n'}], 'operation_description': '\noembed_list is an API endpoint to retrieve embedded content from a specified image URL.\n\nBy using this endpoint, you can retrieve embedded content such as `version`, `type`,\n`width`, `height`, `title`, `author_name`, `author_url` and `license_url`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'image_oembed', 'query_serializer': <class 'catalog.api.serializers.image_serializers.OembedRequestSerializer'>, 'responses': {'200': {'description': 'OK', 'examples': {'application/json': {'author_name': 'Tim Sullivan', 'author_url': 'https://www.secretagencygroup.com', 'height': 4016, 'license_url': 'https://creativecommons.org/publicdomain/zero/1.0/', 'title': 'Tree Bark Photo', 'type': 'photo', 'version': '1.0', 'width': 6016}}, 'schema': <class 'catalog.api.serializers.image_serializers.OembedSerializer'>}, '404': {'description': 'Not Found', 'examples': {'application/json': {'detail': 'An internal server error occurred.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}}

class catalog.api.docs.image_docs.ImageRelated

Bases: MediaRelated

code_examples = [{'lang': 'Bash', 'source': '\n# Get related images for image ID 4bc43a04-ef46-4544-a0c1-63c63f56e276\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/"\n'}]

desc = '\nrecommendations_images_read is an API endpoint to get related images for a specified\nimage ID.\n\nBy using this endpoint, you can get the details of related images such as\n`id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `filesize`, `filetype`, `tags`, `attribution`, `fields_matched`, `mature`, `height`, `width`, `thumbnail`, `detail_url` and `related_url`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'200': {'description': 'OK', 'examples': {'application/json': {'page_count': 1, 'result_count': 10000, 'results': [{'title': 'exam tactics', 'id': '610756ec-ae31-4d5e-8f03-8cc52f31b71d', 'creator': 'Sean MacEntee', 'creator_url': 'https://www.flickr.com/photos/18090920@N07', 'tags': [{'name': 'exam'}, {'name': 'tactics'}], 'url': 'https://live.staticflickr.com/4065/4459771899_07595dc42e.jpg', 'thumbnail': 'https://api.openverse.engineering/v1/thumbs/610756ec-ae31-4d5e-8f03-8cc52f31b71d', 'provider': 'flickr', 'source': 'flickr', 'license': 'by', 'license_version': '2.0', 'license_url': 'https://creativecommons.org/licenses/by/2.0/', 'foreign_landing_url': 'https://www.flickr.com/photos/18090920@N07/4459771899', 'detail_url': 'http://api.openverse.engineering/v1/images/610756ec-ae31-4d5e-8f03-8cc52f31b71d', 'related_url': 'http://api.openverse.engineering/v1/recommendations/images/610756ec-ae31-4d5e-8f03-8cc52f31b71d'}]}}, 'schema': <class 'catalog.api.serializers.image_serializers.ImageSerializer'>}, '404': {'description': 'Not Found', 'examples': {'application/json': {'detail': 'An internal server error occurred.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Get related images for image ID 4bc43a04-ef46-4544-a0c1-63c63f56e276\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/"\n'}], 'operation_description': '\nrecommendations_images_read is an API endpoint to get related images for a specified\nimage ID.\n\nBy using this endpoint, you can get the details of related images such as\n`id`, `title`, `foreign_landing_url`, `url`, `creator`, `creator_url`, `license`, `license_version`, `license_url`, `provider`, `source`, `category`, `filesize`, `filetype`, `tags`, `attribution`, `fields_matched`, `mature`, `height`, `width`, `thumbnail`, `detail_url` and `related_url`.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'image_related', 'responses': {'200': {'description': 'OK', 'examples': {'application/json': {'page_count': 1, 'result_count': 10000, 'results': [{'title': 'exam tactics', 'id': '610756ec-ae31-4d5e-8f03-8cc52f31b71d', 'creator': 'Sean MacEntee', 'creator_url': 'https://www.flickr.com/photos/18090920@N07', 'tags': [{'name': 'exam'}, {'name': 'tactics'}], 'url': 'https://live.staticflickr.com/4065/4459771899_07595dc42e.jpg', 'thumbnail': 'https://api.openverse.engineering/v1/thumbs/610756ec-ae31-4d5e-8f03-8cc52f31b71d', 'provider': 'flickr', 'source': 'flickr', 'license': 'by', 'license_version': '2.0', 'license_url': 'https://creativecommons.org/licenses/by/2.0/', 'foreign_landing_url': 'https://www.flickr.com/photos/18090920@N07/4459771899', 'detail_url': 'http://api.openverse.engineering/v1/images/610756ec-ae31-4d5e-8f03-8cc52f31b71d', 'related_url': 'http://api.openverse.engineering/v1/recommendations/images/610756ec-ae31-4d5e-8f03-8cc52f31b71d'}]}}, 'schema': <class 'catalog.api.serializers.image_serializers.ImageSerializer'>}, '404': {'description': 'Not Found', 'examples': {'application/json': {'detail': 'An internal server error occurred.'}}, 'schema': <class 'catalog.api.serializers.error_serializers.NotFoundErrorSerializer'>}}}

class catalog.api.docs.image_docs.ImageSearch

Bases: MediaSearch

code_examples = [{'lang': 'Bash', 'source': '\n# Example 0: Search for images using single query parameter\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=test"\n\n\n# Example 1: Search for images using multiple query parameters\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=test&license=pdm,by&categories=illustration&page_size=1&page=1"\n\n\n# Example 2: Search for images that are an exact match of Claude Monet\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=%22Claude%20Monet%22"\n\n\n# Example 3: Search for images related to both dog and cat\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=dog+cat"\n\n\n# Example 4: Search for images related to dog or cat, but not necessarily both\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=dog|cat"\n\n\n# Example 5: Search for images related to dog but won\'t include results related to \'pug\'\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=dog -pug"\n\n\n# Example 6: Search for images matching anything with the prefix ‘net’\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=net*"\n\n\n# Example 7: Search for images matching dogs that are either corgis or labrador\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=dogs + (corgis | labrador)"\n\n\n# Example 8: Search for images matching strings close to the term theaterwith a difference of one character\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=theatre~1"\n'}]

desc = '\nimage_search is an API endpoint to search images using a query string.\n\nBy using this endpoint, you can obtain search results based on specified query and\noptionally filter results by\n`q`, `license`, `license_type`, `creator`, `tags`, `title`, `filter_dead`, `extension`, `mature`, `qa`, `page_size`, `page`, `source`, `excluded_source`, `category`, `aspect_ratio` and `size`.\n\n\nResults are ranked in order of relevance and paginated on the basis of the `page` param.\nThe `page_size` param controls the total number of pages.\n\nAlthough there may be millions of relevant records, only the most relevant several\nthousand records can be viewed. This is by design: the search endpoint should be used to\nfind the top 10,000 most relevant results, not for exhaustive search or bulk download of\nevery barely relevant result. As such, the caller should not try to access pages beyond\n`page_count`, or else the server will reject the query.\n\nFor more precise results, you can go to the\n[Openverse Syntax Guide](https://search.creativecommons.org/search-help)\nfor information about creating queries and\n[Apache Lucene Syntax Guide](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html)\nfor information on structuring advanced searches.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'200': {'description': 'OK', 'examples': {'application/json': {'page': 1, 'page_count': 1, 'page_size': 20, 'result_count': 1, 'results': [{'id': '4bc43a04-ef46-4544-a0c1-63c63f56e276', 'title': 'Tree Bark Photo', 'foreign_landing_url': 'https://stocksnap.io/photo/XNVBVXO3B7', 'url': 'https://cdn.stocksnap.io/img-thumbs/960w/XNVBVXO3B7.jpg', 'creator': 'Tim Sullivan', 'creator_url': 'https://www.secretagencygroup.com', 'license': 'cc0', 'license_version': '1.0', 'license_url': 'https://creativecommons.org/publicdomain/zero/1.0/', 'provider': 'stocksnap', 'source': 'stocksnap', 'category': 'photograph', 'filesize': 896128, 'filetype': 'jpg', 'tags': [{'accuracy': None, 'name': 'tree'}, {'accuracy': None, 'name': 'bark'}, {'accuracy': None, 'name': 'texture'}, {'accuracy': None, 'name': 'wood'}, {'accuracy': None, 'name': 'nature'}, {'accuracy': None, 'name': 'pattern'}, {'accuracy': None, 'name': 'rough'}, {'accuracy': None, 'name': 'surface'}, {'accuracy': None, 'name': 'brown'}, {'accuracy': None, 'name': 'old'}, {'accuracy': None, 'name': 'background'}, {'accuracy': None, 'name': 'trunk'}, {'accuracy': None, 'name': 'natural'}, {'accuracy': None, 'name': 'forest'}, {'accuracy': None, 'name': 'detail'}, {'accuracy': None, 'name': 'lumber'}, {'accuracy': None, 'name': 'weathered'}, {'accuracy': None, 'name': 'timber'}, {'accuracy': None, 'name': 'stump'}, {'accuracy': None, 'name': 'closeup'}, {'accuracy': None, 'name': 'root'}], 'attribution': '"Tree Bark Photo" by Tim Sullivan is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/.', 'fields_matched': ['title'], 'mature': False, 'height': 4016, 'width': 6016, 'thumbnail': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/thumb/', 'detail_url': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/', 'related_url': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/'}]}}, 'schema': <class 'catalog.api.serializers.image_serializers.ImageSearchSerializer'>}, '400': {'description': 'Bad Request', 'examples': {'application/json': {'detail': "Invalid input given for fields. 'license' -> License 'PDMNBCG' does not exist.", 'error': 'InputError', 'fields': ['license']}}, 'schema': <class 'catalog.api.serializers.error_serializers.InputErrorSerializer'>}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Example 0: Search for images using single query parameter\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=test"\n\n\n# Example 1: Search for images using multiple query parameters\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=test&license=pdm,by&categories=illustration&page_size=1&page=1"\n\n\n# Example 2: Search for images that are an exact match of Claude Monet\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=%22Claude%20Monet%22"\n\n\n# Example 3: Search for images related to both dog and cat\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=dog+cat"\n\n\n# Example 4: Search for images related to dog or cat, but not necessarily both\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=dog|cat"\n\n\n# Example 5: Search for images related to dog but won\'t include results related to \'pug\'\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=dog -pug"\n\n\n# Example 6: Search for images matching anything with the prefix ‘net’\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=net*"\n\n\n# Example 7: Search for images matching dogs that are either corgis or labrador\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=dogs + (corgis | labrador)"\n\n\n# Example 8: Search for images matching strings close to the term theaterwith a difference of one character\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/?q=theatre~1"\n'}], 'operation_description': '\nimage_search is an API endpoint to search images using a query string.\n\nBy using this endpoint, you can obtain search results based on specified query and\noptionally filter results by\n`q`, `license`, `license_type`, `creator`, `tags`, `title`, `filter_dead`, `extension`, `mature`, `qa`, `page_size`, `page`, `source`, `excluded_source`, `category`, `aspect_ratio` and `size`.\n\n\nResults are ranked in order of relevance and paginated on the basis of the `page` param.\nThe `page_size` param controls the total number of pages.\n\nAlthough there may be millions of relevant records, only the most relevant several\nthousand records can be viewed. This is by design: the search endpoint should be used to\nfind the top 10,000 most relevant results, not for exhaustive search or bulk download of\nevery barely relevant result. As such, the caller should not try to access pages beyond\n`page_count`, or else the server will reject the query.\n\nFor more precise results, you can go to the\n[Openverse Syntax Guide](https://search.creativecommons.org/search-help)\nfor information about creating queries and\n[Apache Lucene Syntax Guide](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html)\nfor information on structuring advanced searches.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'image_search', 'query_serializer': <class 'catalog.api.serializers.image_serializers.ImageSearchRequestSerializer'>, 'responses': {'200': {'description': 'OK', 'examples': {'application/json': {'page': 1, 'page_count': 1, 'page_size': 20, 'result_count': 1, 'results': [{'id': '4bc43a04-ef46-4544-a0c1-63c63f56e276', 'title': 'Tree Bark Photo', 'foreign_landing_url': 'https://stocksnap.io/photo/XNVBVXO3B7', 'url': 'https://cdn.stocksnap.io/img-thumbs/960w/XNVBVXO3B7.jpg', 'creator': 'Tim Sullivan', 'creator_url': 'https://www.secretagencygroup.com', 'license': 'cc0', 'license_version': '1.0', 'license_url': 'https://creativecommons.org/publicdomain/zero/1.0/', 'provider': 'stocksnap', 'source': 'stocksnap', 'category': 'photograph', 'filesize': 896128, 'filetype': 'jpg', 'tags': [{'accuracy': None, 'name': 'tree'}, {'accuracy': None, 'name': 'bark'}, {'accuracy': None, 'name': 'texture'}, {'accuracy': None, 'name': 'wood'}, {'accuracy': None, 'name': 'nature'}, {'accuracy': None, 'name': 'pattern'}, {'accuracy': None, 'name': 'rough'}, {'accuracy': None, 'name': 'surface'}, {'accuracy': None, 'name': 'brown'}, {'accuracy': None, 'name': 'old'}, {'accuracy': None, 'name': 'background'}, {'accuracy': None, 'name': 'trunk'}, {'accuracy': None, 'name': 'natural'}, {'accuracy': None, 'name': 'forest'}, {'accuracy': None, 'name': 'detail'}, {'accuracy': None, 'name': 'lumber'}, {'accuracy': None, 'name': 'weathered'}, {'accuracy': None, 'name': 'timber'}, {'accuracy': None, 'name': 'stump'}, {'accuracy': None, 'name': 'closeup'}, {'accuracy': None, 'name': 'root'}], 'attribution': '"Tree Bark Photo" by Tim Sullivan is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/.', 'fields_matched': ['title'], 'mature': False, 'height': 4016, 'width': 6016, 'thumbnail': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/thumb/', 'detail_url': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/', 'related_url': 'https://api.openverse.engineering/v1/images/4bc43a04-ef46-4544-a0c1-63c63f56e276/related/'}]}}, 'schema': <class 'catalog.api.serializers.image_serializers.ImageSearchSerializer'>}, '400': {'description': 'Bad Request', 'examples': {'application/json': {'detail': "Invalid input given for fields. 'license' -> License 'PDMNBCG' does not exist.", 'error': 'InputError', 'fields': ['license']}}, 'schema': <class 'catalog.api.serializers.error_serializers.InputErrorSerializer'>}}}

class catalog.api.docs.image_docs.ImageStats

Bases: MediaStats

code_examples = [{'lang': 'Bash', 'source': '\n# Get the statistics for image sources\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/stats/"\n'}]

desc = '\nimage_stats is an API endpoint to get a list of all content providers and their\nrespective number of images in the Openverse catalog.\n\n\nYou can use this endpoint to get details about content providers such as `source_name`,\n`display_name`, and `source_url` along with a count of the number of individual items\nindexed from them.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

responses = {'200': {'description': 'OK', 'examples': {'application/json': [{'source_name': 'flickr', 'display_name': 'Flickr', 'source_url': 'https://www.flickr.com', 'logo_url': None, 'media_count': 2500}, {'source_name': 'stocksnap', 'display_name': 'StockSnap', 'source_url': 'https://stocksnap.io', 'logo_url': None, 'media_count': 2500}]}, 'schema': ProviderSerializer(many=True):     source_name = CharField(help_text='The source of the media, e.g. flickr', source='provider_identifier')     display_name = CharField(help_text='The name of content provider, e.g. Flickr', source='provider_name')     source_url = URLField(help_text='The URL of the source, e.g. https://www.flickr.com', source='domain_name')     logo_url = ReadOnlyField(default=None, help_text='Deprecated and unused. Always `null`.')     media_count = SerializerMethodField(help_text='The number of media items indexed from the source.')}}

swagger_setup = {'code_examples': [{'lang': 'Bash', 'source': '\n# Get the statistics for image sources\ncurl \\\n  -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" \\\n  "https://api.openverse.engineering/v1/images/stats/"\n'}], 'operation_description': '\nimage_stats is an API endpoint to get a list of all content providers and their\nrespective number of images in the Openverse catalog.\n\n\nYou can use this endpoint to get details about content providers such as `source_name`,\n`display_name`, and `source_url` along with a count of the number of individual items\nindexed from them.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'image_stats', 'responses': {'200': {'description': 'OK', 'examples': {'application/json': [{'source_name': 'flickr', 'display_name': 'Flickr', 'source_url': 'https://www.flickr.com', 'logo_url': None, 'media_count': 2500}, {'source_name': 'stocksnap', 'display_name': 'StockSnap', 'source_url': 'https://stocksnap.io', 'logo_url': None, 'media_count': 2500}]}, 'schema': ProviderSerializer(many=True):     source_name = CharField(help_text='The source of the media, e.g. flickr', source='provider_identifier')     display_name = CharField(help_text='The name of content provider, e.g. Flickr', source='provider_name')     source_url = URLField(help_text='The URL of the source, e.g. https://www.flickr.com', source='domain_name')     logo_url = ReadOnlyField(default=None, help_text='Deprecated and unused. Always `null`.')     media_count = SerializerMethodField(help_text='The number of media items indexed from the source.')}}}

class catalog.api.docs.image_docs.ImageThumbnail

Bases: object

desc = '\nthumbnail is an API endpoint to retrieve the scaled down and compressed thumbnail\nof an image.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

swagger_setup = {'operation_description': '\nthumbnail is an API endpoint to retrieve the scaled down and compressed thumbnail\nof an image.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n', 'operation_id': 'image_thumbnail', 'query_serializer': <class 'catalog.api.serializers.media_serializers.MediaThumbnailRequestSerializer'>}

catalog.api.docs.media_docs module

class catalog.api.docs.media_docs.MediaComplain

Bases: object

desc = '\nBy using this endpoint, you can report a file if it infringes copyright, contains mature\nor sensitive content and others.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

class catalog.api.docs.media_docs.MediaDetail

Bases: object

desc = '\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

class catalog.api.docs.media_docs.MediaRelated

Bases: object

desc = '\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

class catalog.api.docs.media_docs.MediaSearch

Bases: object

desc = '\nResults are ranked in order of relevance and paginated on the basis of the `page` param.\nThe `page_size` param controls the total number of pages.\n\nAlthough there may be millions of relevant records, only the most relevant several\nthousand records can be viewed. This is by design: the search endpoint should be used to\nfind the top 10,000 most relevant results, not for exhaustive search or bulk download of\nevery barely relevant result. As such, the caller should not try to access pages beyond\n`page_count`, or else the server will reject the query.\n\nFor more precise results, you can go to the\n[Openverse Syntax Guide](https://search.creativecommons.org/search-help)\nfor information about creating queries and\n[Apache Lucene Syntax Guide](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html)\nfor information on structuring advanced searches.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

class catalog.api.docs.media_docs.MediaStats

Bases: object

desc = '\nYou can use this endpoint to get details about content providers such as `source_name`,\n`display_name`, and `source_url` along with a count of the number of individual items\nindexed from them.\n\n\nYou can refer to the cURL request samples for examples on how to consume this\nendpoint.\n'

catalog.api.docs.media_docs.fields_to_md(field_names)

Create a Markdown representation of the given list of names to use in Swagger docs.

Parameters:

field_names – the list of field names to convert to Markdown

Returns:

the names as a Markdown string

Module contents