500px-api

# 500px-API  <p>  <a href="https://github.com/Scrip7/500px-api/actions/workflows/ci.yml"><img src="https://img.shields.io/github/workflow/status/Scrip7/500px-api/CI?color=2fb54c&label=CI&logo=github&logoColor=d9ecde" alt="CI"></a>  <a href="https://codecov.io/gh/Scrip7/500px-api"><img src="https://img.shields.io/codecov/c/github/scrip7/500px-api?color=2fb54c" alt="Code Coverage"></a>  <a href="https://npmjs.com/package/500px-api"><img src="https://img.shields.io/npm/dy/500px-api?color=2fb54c" alt="NPM Downloads"></a>  <a href="https://npmjs.com/package/500px-api"><img src="https://img.shields.io/npm/v/500px-api.svg" alt="NPM"></a>  <a href="https://github.com/Scrip7/discord-redgifs-bot/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Scrip7/500px-api?color=blue" alt="License"></a> <br />  <a href="https://codefactor.io/repository/github/scrip7/500px-api"><img src="https://img.shields.io/codefactor/grade/github/scrip7/500px-api?color=2fb54c&label=Codefactor" alt="CodeFactor"></a>  <a href="https://codeclimate.com/github/Scrip7/500px-api/maintainability"><img src="https://img.shields.io/codeclimate/maintainability/Scrip7/500px-api?color=2fb54c" alt="Maintainability"></a>  <a href="https://snyk.io/test/github/scrip7/500px-api?targetFile=package.json"><img src="https://img.shields.io/snyk/vulnerabilities/github/scrip7/500px-api?color=2fb54c" alt="Known Vulnerabilities"></a>  <a href="http://commitizen.github.io/cz-cli/"><img src="https://img.shields.io/badge/commitizen-friendly-2fb54c.svg?color=d9ecde" alt="Commitizen friendly"></a>  <a href="https://github.com/Scrip7/500px-api/blob/main/CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-blue.svg?color=d9ecde" alt="Contributing"></a> </p>   <a href="https://github.com/Scrip7/500px-api/"> <img src="https://raw.githubusercontent.com/Scrip7/500px-api/main/images/500px_logo.svg" width="260" align="right"> </a> > [500px API](https://npmjs.com/package/500px-api) is an unofficial package to fetch photos, users, photographers, camera equipment details, and other information from the 500px.com website!  ## When will it be ready? ![Who knows?](https://i.imgur.com/6xfbPzs.gif) ## Table of contents - [What is 500px?](#what-is-500px) - [Why 500px-api?](#why-500px-api) - [Features](#features) - [Coverage](#coverage) - [Installing](#installing) - [Get started](#get-started) - [Method options](#method-options) - [Categories](#categories) - [Hidden categories](#hidden-categories) - [Image sizes](#image-sizes) - [Standard sizes](#standard-sizes) - [Longest edge sizes](#longest-edge-sizes) - [Cropped sizes](#cropped-sizes) - [Contributing](#contributing) - [Resources](#resources) ## What is 500px? [500px](https://500px.com/) (pronounced "five hundred p-x") is a photography community where you can get immediate exposure with your first upload, connect and share your photos with the world, and grow as a photographer from anywhere. ## Why 500px-api? According to [this support post](https://support.500px.com/hc/en-us/articles/360002435653-API), they no longer provide official API to third-parties. > The history of 500px has always encouraged creative development, but as of January 24th 2018, 500px will no longer be offering free access to our API. > This decision was made in order to protect our assets and improve our website's performance. > On June 15th, access to the API was shut down. > This is part of a larger strategic shift focusing our energy on continuing to build the world’s best photography community at 500px.com. That's the main reason I developed and publish this package. [🔼 jump to the top](#table-of-contents) ## Features - Proxy support - Random `User-Agent` header for each `Client` ## Coverage - Photo - Discover - Search - Comments ## Installing Using yarn (recommended): ```bash yarn add 500px-api ``` Using npm: ```bash npm install 500px-api ``` ## Get started See the [examples](https://github.com/Scrip7/500px-api/tree/main/examples) subdirectory for simple API calls. > If you have a use-case in mind which isn't well-represented by the examples, please [create an issue](https://github.com/Scrip7/500px-api/issues/new) or [submit a Pull Request](https://github.com/Scrip7/500px-api/blob/main/CONTRIBUTING.md). [🔼 jump to the top](#table-of-contents) ## Method Options Each method has a lot of options, and **some of them** require pre-context. First, I'll describe what those options are and the best practices to use them in your application. [🔼 jump to the top](#table-of-contents) ### Categories Categories of photos may be specified by their ID or string name, depending on the API method. > Avoid [hard coding](https://en.wikipedia.org/wiki/Hard_coding) these **IDs** and **names** in your application! ⚠️ The best practice to use them in method options, is using [`Category`](https://github.com/Scrip7/500px-api/blob/main/src/constants/enums.ts) enum. If you use this coding approach, in case if we change their values in the future, you no longer need to update your code, and this further ensures the **stability** of your code. ```TypeScript import { Category } from '500px-api'; /** * Return the String name of the category. */ console.log(Category.FAMILY); // Family ``` Sometimes after sending an API call, you might want to convert the category's numeric IDs to human-readable names, by using [`CategoriesHelper`](https://github.com/Scrip7/500px-api/blob/main/src/helpers/categories.ts) class. ```TypeScript import { CategoriesHelper } from '500px-api'; /** * Converts Numeric category ID to it's name. */ console.log(CategoriesHelper.convertIdToName(20)); // Family ``` ID | Name | Enum Usage ---|-----------------------|-------------------- 10 | `Abstract` | `Category.ABSTRACT` 29 | `Aerial` | `Category.AERIAL` 11 | `Animals` | `Category.ANIMALS` 5 | `Black and White` | `Category.BLACK_AND_WHITE` 1 | `Celebrities` | `Category.CELEBRITIES` 15 | `Commercial` | `Category.COMMERCIAL` 16 | `Concert` | `Category.CONCERT` 20 | `Family` | `Category.FAMILY` 14 | `Fashion` | `Category.FASHION` 2 | `Film` | `Category.FILM` 24 | `Fine Art` | `Category.FINE_ART` 23 | `Food` | `Category.FOOD` 3 | `Journalism` | `Category.JOURNALISM` 8 | `Landscapes` | `Category.LANDSCAPES` 12 | `Macro` | `Category.MACRO` 18 | `Nature` | `Category.NATURE` 30 | `Night` | `Category.NIGHT` 7 | `People` | `Category.PEOPLE` 19 | `Performing Arts` | `Category.PERFORMING_ARTS` 9 | `City & Architecture` | `Category.CITY_AND_ARCHITECTURE` 17 | `Sport` | `Category.SPORT` 6 | `Still Life` | `Category.STILL_LIFE` 21 | `Street` | `Category.STREET` 26 | `Transportation` | `Category.TRANSPORTATION` 13 | `Travel` | `Category.TRAVEL` 22 | `Underwater` | `Category.UNDERWATER` 27 | `Urban Exploration` | `Category.URBAN_EXPLORATION` 25 | `Wedding` | `Category.WEDDING` 0 | `Uncategorized` | `Category.UNCATEGORIZED` [🔼 jump to the top](#table-of-contents) #### Hidden categories For several reasons, such as the type of audience or having an NSFW tag, the 500px.com website keeps these categories hidden from the public eye. You can use these **IDs** and **names** the same way as usual [categories](#categories), but you have to be aware the content is for mature users. ID | Name | Enum Usage ---|-----------|------------------------- 31 | `Boudoir` | `Category.BOUDOIR` 4 | `Nude` | `Category.NUDE` [🔼 jump to the top](#table-of-contents) ### Image sizes To fetch images of different sizes, you have to provide an array of numeric IDs as a method option. Each of these IDs represents different image sizes. > Avoid [hard coding](https://en.wikipedia.org/wiki/Hard_coding) these **IDs** in your application! ⚠️ The best practice to use them in method options, is using [`ImageSize`](https://github.com/Scrip7/500px-api/blob/main/src/constants/enums.ts) enum. ```TypeScript import { ImageSize } from '500px-api'; console.log(ImageSize.STANDARD_WIDTH_4096); // 15 ``` > I have no idea what the **K**, and **S** columns are stands for, but I implemented them in this package and the documentation anyway. If you have any more information about them, feel free to [open a new issue](https://github.com/Scrip7/500px-api/issues/new) to explain them. [🔼 jump to the top](#table-of-contents) #### Standard sizes If the width or height is empty, it means that they'll be calculated automatically (consider it as `auto`). ```TypeScript import { ImageSize } from '500px-api'; const sizes = [ // Standard width ImageSize.STANDARD_WIDTH_1000_Q50, ImageSize.STANDARD_WIDTH_2000_Q75, ImageSize.STANDARD_WIDTH_4096, // Standard height ImageSize.STANDARD_HEIGHT_300_Q80, ImageSize.STANDARD_HEIGHT_300, ImageSize.STANDARD_HEIGHT_450_Q80, ImageSize.STANDARD_HEIGHT_450_Q50, ImageSize.STANDARD_HEIGHT_600_Q80, ImageSize.STANDARD_HEIGHT_600, ImageSize.STANDARD_HEIGHT_1080, ]; ``` ID | Width | Height | Quality | K | S | Watermark | Enum Usage -------|:------:|:------:|:-------:|:--:|:--:|:---------:|------------------------------------ **23** | `1000` | | `50` | | | ✖️ | `ImageSize.STANDARD_WIDTH_1000_Q50` **24** | `2000` | | `75` | | | ✖️ | `ImageSize.STANDARD_WIDTH_2000_Q75` **15** | `4096` | | | | ✔️ | ✖️ | `ImageSize.STANDARD_WIDTH_4096` **32** | | `300` | `80` | | | ✖️ | `ImageSize.STANDARD_HEIGHT_300_Q80` **20** | | `300` | | | | ✖️ | `ImageSize.STANDARD_HEIGHT_300` **31** | | `450` | `80` | | | ✖️ | `ImageSize.STANDARD_HEIGHT_450_Q80` **22** | | `450` | `50` | | | ✖️ | `ImageSize.STANDARD_HEIGHT_450_Q50` **33** | | `600` | `80` | ✔️ | | ✖️ | `ImageSize.STANDARD_HEIGHT_600_Q80` **21** | | `600` | | ✔️ | | ✖️ | `ImageSize.STANDARD_HEIGHT_600` **6** | | `1080` | | ✔️ | | ✖️ | `ImageSize.STANDARD_HEIGHT_1080` [🔼 jump to the top](#table-of-contents) #### Longest edge sizes Depending on the overall height and width of the image, the longest edge of the image will be set to the **Longest Edge** column's value, and the other edge will be considered as `auto`. ```TypeScript import { ImageSize } from '500px-api'; const sizes = [ // Longest edge ImageSize.LONGEST_EDGE_256, ImageSize.LONGEST_EDGE_900, ImageSize.LONGEST_EDGE_900_WATERMARK, ImageSize.LONGEST_EDGE_1000_Q80, ImageSize.LONGEST_EDGE_1080, ImageSize.LONGEST_EDGE_1170, ImageSize.LONGEST_EDGE_1500_Q80, ImageSize.LONGEST_EDGE_1600, ImageSize.LONGEST_EDGE_2000_Q80, ImageSize.LONGEST_EDGE_2048, ImageSize.LONGEST_EDGE_4096, ]; ``` ID | Longest Edge | Quality | K | S | Watermark | Enum Usage ---------|:------------:|:-------:|:--:|:--:|:---------:|------------------------------------ **30** | `256` | | | | ✖️ | `ImageSize.LONGEST_EDGE_256` **4** | `900` | | | | ✖️ | `ImageSize.LONGEST_EDGE_900` **14** | `900` | | ✔️ | ✔️ | ✔️ | `ImageSize.LONGEST_EDGE_900_WATERMARK` **34** | `1000` | `80` | ✔️ | | ✖️ | `ImageSize.LONGEST_EDGE_1000_Q80` **1080** | `1080` | | ✔️ | | ✖️ | `ImageSize.LONGEST_EDGE_1080` **5** | `1170` | | ✔️ | | ✖️ | `ImageSize.LONGEST_EDGE_1170` **35** | `1500` | `80` | ✔️ | | ✖️ | `ImageSize.LONGEST_EDGE_1500_Q80` **1600** | `1600` | | ✔️ | | ✖️ | `ImageSize.LONGEST_EDGE_1600` **36** | `2000` | `80` | ✔️ | | ✖️ | `ImageSize.LONGEST_EDGE_2000_Q80` **2048** | `2048` | | ✔️ | | ✖️ | `ImageSize.LONGEST_EDGE_2048` **4096** | `4096` | | ✔️ | | ✖️ | `ImageSize.LONGEST_EDGE_4096` [🔼 jump to the top](#table-of-contents) #### Cropped sizes Regardless of the original size of the photo, they will be cropped and will never be larger than the specified size. ```TypeScript import { ImageSize } from '500px-api'; const sizes = [ // Cropped ImageSize.CROPPED_70x70, ImageSize.CROPPED_100x100, ImageSize.CROPPED_140x140_Q50, ImageSize.CROPPED_200x200, ImageSize.CROPPED_280x280, ImageSize.CROPPED_440x440, ImageSize.CROPPED_580x580, ImageSize.CROPPED_600x600, ImageSize.CROPPED_680x680, ]; ``` ID | Width | Height | Quality | S | Watermark | Enum Usage --------|:-----:|:------:|:-------:|:--:|:---------:|-------------------------------- **1** | `70` | `70` | | | ✖️ | `ImageSize.CROPPED_70x70` **100** | `100` | `100` | | | ✖️ | `ImageSize.CROPPED_100x100` **2** | `140` | `140` | `50` | | ✖️ | `ImageSize.CROPPED_140x140_Q50` **200** | `200` | `200` | | | ✖️ | `ImageSize.CROPPED_200x200` **3** | `280` | `280` | | | ✖️ | `ImageSize.CROPPED_280x280` **440** | `440` | `440` | | | ✖️ | `ImageSize.CROPPED_440x440` **11** | `580` | `580` | | ✔️ | ✖️ | `ImageSize.CROPPED_580x580` **600** | `600` | `600` | | | ✖️ | `ImageSize.CROPPED_600x600` **13** | `680` | `680` | | ✔️ | ✖️ | `ImageSize.CROPPED_680x680` [🔼 jump to the top](#table-of-contents) ## Contributing Please read the [CONTRIBUTING.md](https://github.com/Scrip7/500px-api/blob/main/CONTRIBUTING.md) file for details on our code of conduct, the process of running tests, and submitting pull requests to us. [🔼 jump to the top](#table-of-contents) ## Resources - [500px Legacy API](https://github.com/500px/legacy-api-documentation) [🔼 jump to the top](#table-of-contents)