500px-api

This is an unofficial package to fetch photos, users, photographers, camera equipment details, and other information from the 500px.com website.

Usage no npm install needed!

<script type="module">
  import 00pxApi from 'https://cdn.skypack.dev/500px-api';
</script>

README

500px-API

CI Code Coverage NPM Downloads NPM License
CodeFactor Maintainability Known Vulnerabilities Commitizen friendly Contributing

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?

Table of contents

What is 500px?

500px (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, 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

Features

  • Proxy support
  • Random User-Agent header for each Client

Coverage

  • Photo
    • Discover
    • Search
    • Comments

Installing

Using yarn (recommended):

yarn add 500px-api

Using npm:

npm install 500px-api

Get started

See the 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 or submit a Pull Request.

๐Ÿ”ผ jump to the top

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

Categories

Categories of photos may be specified by their ID or string name, depending on the API method.

Avoid hard coding these IDs and names in your application! โš ๏ธ

The best practice to use them in method options, is using Category 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.

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 class.

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

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, 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

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 these IDs in your application! โš ๏ธ

The best practice to use them in method options, is using ImageSize enum.

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 to explain them.

๐Ÿ”ผ jump to the top

Standard sizes

If the width or height is empty, it means that they'll be calculated automatically (consider it as auto).

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

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.

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

Cropped sizes

Regardless of the original size of the photo, they will be cropped and will never be larger than the specified size.

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

Contributing

Please read the 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

Resources

๐Ÿ”ผ jump to the top