def get(self, request, identifier, format=None):
related, result_count = search_controller.related_images(
uuid=identifier, index='image', request=request, filter_dead=True)
context = {'request': request}
serialized_related = ImageSerializer(related,
many=True,
context=context).data
response_data = {
RESULT_COUNT: result_count,
PAGE_COUNT: 0,
RESULTS: serialized_related
}
serialized_response = ImageSearchResultsSerializer(data=response_data)
return Response(status=200, data=serialized_response.initial_data)
def get(self, request, format=None):
# Parse and validate query parameters
params = ImageSearchQueryStringSerializer(data=request.query_params)
if not params.is_valid():
return input_error_response(params.errors)
hashed_ip = hash(_get_user_ip(request))
page_param = params.data[PAGE]
page_size = params.data[PAGESIZE]
qa = params.data[QA]
filter_dead = params.data[FILTER_DEAD]
search_index = 'search-qa' if qa else 'image'
try:
results, page_count, result_count = search_controller.search(
params,
search_index,
page_size,
hashed_ip,
request,
filter_dead,
page=page_param
)
except ValueError as value_error:
return input_error_response(str(value_error))
context = {'request': request}
serialized_results = ImageSerializer(
results, many=True, context=context
).data
if len(results) < page_size and page_count == 0:
result_count = len(results)
response_data = {
RESULT_COUNT: result_count,
PAGE_COUNT: page_count,
PAGE_SIZE: len(results),
RESULTS: serialized_results
}
serialized_response = ImageSearchResultsSerializer(data=response_data)
return Response(status=200, data=serialized_response.initial_data)
class SearchImages(APIView):
swagger_schema = CustomAutoSchema
image_search_description = \
"""
image_search is an API endpoint to search images using a query string.
By using this endpoint, you can obtain search results based on specified
query and optionally filter results by `license`, `license_type`,
`page`, `page_size`, `creator`, `tags`, `title`, `filter_dead`,
`source`, `extension`, `categories`, `aspect_ratio`, `size`, `mature`,
and `qa`. Results are ranked in order of relevance.
Although there may be millions of relevant records, only the most
relevant several thousand records can be viewed. This is by design:
the search endpoint should be used to find the top 10,000 most relevant
results, not for exhaustive search or bulk download of every barely
relevant result. As such, the caller should not try to access pages
beyond `page_count`, or else the server will reject the query.
For more precise results, you can go to the
[CC Search Syntax Guide](https://search.creativecommons.org/search-help)
for information about creating queries and
[Apache Lucene Syntax Guide](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html)
for information on structuring advanced searches.
You can refer to Bash's Request Samples for examples on how to use
this endpoint.
""" # noqa
image_search_response = {
"200":
openapi.Response(description="OK",
examples=image_search_200_example,
schema=ImageSearchResultsSerializer(many=True)),
"400":
openapi.Response(description="Bad Request",
examples=image_search_400_example,
schema=InputErrorSerializer)
}
image_search_bash = \
"""
# Example 1: Search for an exact match of Claude Monet
curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q="Claude Monet"
# Example 2: Search for images related to both dog and cat
curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=dog+cat
# Example 3: Search for images related to dog or cat, but not necessarily both
curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=dog|cat
# Example 4: Search for images related to dog but won't include results related to 'pug'
curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=dog -pug
# Example 5: Search for images matching anything with the prefix ‘net’
curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=net*
# Example 6: Search for images that match dogs that are either corgis or labrador
curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=dogs + (corgis | labrador)
# Example 7: Search for images that match strings close to the term theater with a difference of one character
curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=theatre~1
# Example 8: Search for images using single query parameter
curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=test
# Example 9: Search for images using multiple query parameters
curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=test&license=pdm,by&categories=illustration&page_size=1&page=1
""" # noqa
@swagger_auto_schema(operation_id='image_search',
operation_description=image_search_description,
query_serializer=ImageSearchQueryStringSerializer,
responses=image_search_response,
code_examples=[{
'lang': 'Bash',
'source': image_search_bash
}])
def get(self, request, format=None):
# Parse and validate query parameters
params = ImageSearchQueryStringSerializer(data=request.query_params)
if not params.is_valid():
return input_error_response(params.errors)
hashed_ip = hash(_get_user_ip(request))
page_param = params.data[PAGE]
page_size = params.data[PAGESIZE]
qa = params.data[QA]
filter_dead = params.data[FILTER_DEAD]
search_index = 'search-qa' if qa else 'image'
try:
results, num_pages, num_results = search_controller.search(
params,
search_index,
page_size,
hashed_ip,
request,
filter_dead,
page=page_param)
except ValueError as value_error:
return input_error_response(value_error)
context = {'request': request}
serialized_results = ImageSerializer(results,
many=True,
context=context).data
if len(results) < page_size and num_pages == 0:
num_results = len(results)
response_data = {
RESULT_COUNT: num_results,
PAGE_COUNT: num_pages,
PAGE_SIZE: len(results),
RESULTS: serialized_results
}
serialized_response = ImageSearchResultsSerializer(data=response_data)
return Response(status=200, data=serialized_response.initial_data)
class SearchImages(APIView):
"""
Search for images by a query string. Optionally, filter results by specific
licenses, or license "types" (commercial use allowed, modification allowed,
etc). Results are ranked in order of relevance.
Refer to the Lucene syntax guide for information on structuring advanced
searches. https://lucene.apache.org/core/2_9_4/queryparsersyntax.html
Although there may be millions of relevant records, only the most relevant
several thousand records can be viewed. This is by design: the search
endpoint should be used to find the top N most relevant results, not for
exhaustive search or bulk download of every barely relevant result.
As such, the caller should not try to access pages beyond `page_count`,
or else the server will reject the query.
"""
@swagger_auto_schema(operation_id='image_search',
query_serializer=ImageSearchQueryStringSerializer,
responses={
200: ImageSearchResultsSerializer(many=True),
400: InputErrorSerializer,
})
def get(self, request, format=None):
# Parse and validate query parameters
params = ImageSearchQueryStringSerializer(data=request.query_params)
if not params.is_valid():
return input_error_response(params.errors)
hashed_ip = hash(_get_user_ip(request))
page_param = params.data[PAGE]
page_size = params.data[PAGESIZE]
qa = params.data[QA]
filter_dead = params.data[FILTER_DEAD]
search_index = 'search-qa' if qa else 'image'
try:
results, num_pages, num_results = search_controller.search(
params,
search_index,
page_size,
hashed_ip,
request,
filter_dead,
page=page_param)
except ValueError as value_error:
return input_error_response(value_error)
context = {'request': request}
serialized_results = ImageSerializer(results,
many=True,
context=context).data
if len(results) < page_size and num_pages == 0:
num_results = len(results)
response_data = {
RESULT_COUNT: num_results,
PAGE_COUNT: num_pages,
PAGE_SIZE: len(results),
RESULTS: serialized_results
}
serialized_response = ImageSearchResultsSerializer(data=response_data)
return Response(status=200, data=serialized_response.initial_data)
class SearchImages(APIView):
image_search_description = \
"""
Search for images by a query string. Optionally, filter results by specific
licenses, or license "types" (commercial use allowed, modification allowed,
etc). Results are ranked in order of relevance.
Refer to the Lucene syntax guide for information on structuring advanced
searches. https://lucene.apache.org/core/2_9_4/queryparsersyntax.html
Although there may be millions of relevant records, only the most relevant
several thousand records can be viewed. This is by design: the search
endpoint should be used to find the top N most relevant results, not for
exhaustive search or bulk download of every barely relevant result.
As such, the caller should not try to access pages beyond `page_count`,
or else the server will reject the query.
Example using single query parameter:
```
$ curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=test
```
Example using multiple query parameters:
```
$ curl -H "Authorization: Bearer DLBYIcfnKfolaXKcmMC8RIDCavc2hW" https://api.creativecommons.engineering/v1/images?q=test&license=pdm,by&categories=illustration&page_size=1&page=1
```
""" # noqa
image_search_response = {
"200":
openapi.Response(description="OK",
examples=image_search_200_example,
schema=ImageSearchResultsSerializer(many=True)),
"400":
openapi.Response(description="Bad Request",
examples=image_search_400_example,
schema=InputErrorSerializer)
}
@swagger_auto_schema(operation_id='image_search',
operation_description=image_search_description,
query_serializer=ImageSearchQueryStringSerializer,
responses=image_search_response)
def get(self, request, format=None):
# Parse and validate query parameters
params = ImageSearchQueryStringSerializer(data=request.query_params)
if not params.is_valid():
return input_error_response(params.errors)
hashed_ip = hash(_get_user_ip(request))
page_param = params.data[PAGE]
page_size = params.data[PAGESIZE]
qa = params.data[QA]
filter_dead = params.data[FILTER_DEAD]
search_index = 'search-qa' if qa else 'image'
try:
results, num_pages, num_results = search_controller.search(
params,
search_index,
page_size,
hashed_ip,
request,
filter_dead,
page=page_param)
except ValueError as value_error:
return input_error_response(value_error)
context = {'request': request}
serialized_results = ImageSerializer(results,
many=True,
context=context).data
if len(results) < page_size and num_pages == 0:
num_results = len(results)
response_data = {
RESULT_COUNT: num_results,
PAGE_COUNT: num_pages,
PAGE_SIZE: len(results),
RESULTS: serialized_results
}
serialized_response = ImageSearchResultsSerializer(data=response_data)
return Response(status=200, data=serialized_response.initial_data)
