API docs are generated from the package docstrings and can be built locally or published with the included GitHub Pages workflow.
Mercapi is a Python wrapper for mercari.jp API. It's capable of producing HTTP requests implementing security mechanisms employed in native mercari.jp web app. Requests and responses are mapped to custom classes with type-hinting and documentation.
First, install the mercapi package using the package manager of your choice.
As an example, we want to run the search query sharpnel.
`python from mercapi import Mercapi
m = Mercapi() results = await m.search('sharpnel')
print(f'Found {results.meta.num_found} results') for item in results.items: print(f'Name: {item.name}\nPrice: {item.price}\n') `
We can use a single result object to retrieve full details of the listing.
`python item = results.items[0] full_item = await item.full_item()
print(full_item.description) `
Or get it directly using an ID.
`python item = await m.item('m90925725213')
print(item.description) `
Mercari web uses a dedicated image-search endpoint, and Mercapi.image_search() mirrors that flow. Pass raw JPEG bytes or a base64-encoded JPEG string.
`python from mercapi import Mercapi
with open('query.jpg', 'rb') as f: image_bytes = f.read()
m = Mercapi() results = await m.image_search(image_bytes)
print(f'Returned {len(results.items)} image matches on this page') for item in results.items[:5]: print(f'{item.name} | {item.real_price}') `
Notes:
- Mercari currently expects JPEG input and may reject images larger than 400x400.
- The image-search response does not include a total hit count. For image searches, esults.meta.num_found reflects the number of items returned on the current page.
- Paging still works through esults.next_page() when esults.meta.next_page_token is present.
The published API docs are generated from the package docstrings and this README. To build them locally:
�ash poetry install --with docs poetry run pdoc -o html mercapi
Refer to mercapi.mercapi.Mercapi documentation for all implemented features.
Examples above are not executable as-is. If you want to try them out, run python example.py and adapt the sample inputs.