User Guide

This guide describes the process to obtain body measurements from two photos.

The overall flow is as follows:

1. Authenticate
2. Request an Estimation ID
3. Post the photos
4. Get the Measurements

Authenticate

First, request an authentication token using the client ID that you received when registering your application with Bodygram. In this guide, we assume that environment variable CLIENT_ID contains your client ID.

Below is an example request to obtain an authentication token:

curl -X GET \
  'https://partner-auth.bodygram.com/tokens/anonymous?client_id='$CLIENT_ID   

curl -X GET \
  'https://partner-auth.stg.bodygram.cc/tokens/anonymous?client_id='$CLIENT_ID   

The response should be similar to the following:

{
    "uid": "01FYPXZCZ2YA0RE35RGP5K58GR", 
    "access_token": "abc123"
}

The remainder of this guide assumes that the access token is stored in the ACCESS_TOKEN environment variable.

Request an Estimation ID

Next, request an estimation ID by posting basic information about the user you want to obtain body measurements for. The estimation ID will be used in subsequent steps to post the user's photos.

The following is a list of parameters you need to specify to acquire an estimation ID.

The request should be similar to the following example; don't forget to set the authentication token in the header:

curl -X POST \
  'https://api2.bodygram.com/estimation' \
  -H 'accept: application/json' \
  -H 'Access-Token: '$ACCESS_TOKEN \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id='$CLIENT_ID'&measurement_id='$MEASUREMENT_ID'&height=1778&weight=68500&age=33&gender=male&lang=en'

curl -X POST \
  'https://api2.stg.bodygram.cc/estimation' \
  -H 'accept: application/json' \
  -H 'Access-Token: '$ACCESS_TOKEN \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id='$CLIENT_ID'&measurement_id='$MEASUREMENT_ID'&height=1778&weight=68500&age=33&gender=male&lang=en'

The response contains the requested estimation ID:

{
  "created_at": "2022-01-01T00:01:33.7",
  "estimation_id": "03KVW300KBJRZFBA29VDFD9AZW"
}

Post the photos

Next, post the front and right photos of the user. Both photos must satisfy the following requirements:

• Format: JPEG
• Size: No more than 3 MB
• Resolution:
  • Apect ratio 9:16 (width × height)
  • Recommended: 1080 × 1920
  • Minimum: 720 × 1280
• EXIF information is recommended but optional

The success and accuracy of the estimated body measurements strongly depend on the body poses users are taking on their pictures. To maximize success rate and quality, we recommend following the pose instructions in this page.

The following is a list of parameters to provide when posting the front and right photos.

The following is an example request to send the front photo:

curl -X POST 'https://api2.bodygram.com/estimation/'$ESTIMATION_ID'/image' \
-H 'accept: application/json' \
-H 'Access-Token: '$ACCESS_TOKEN'' \
-H 'Content-Type: multipart/form-data' \
--form 'client_id="'$CLIENT_ID'"' \
--form 'pattern="front"' \
--form 'image=@"'/path_to/front_photo.jpg'"'

curl -X POST 'https://api2.stg.bodygram.cc/estimation/'$ESTIMATION_ID'/image' \
-H 'accept: application/json' \
-H 'Access-Token: '$ACCESS_TOKEN'' \
-H 'Content-Type: multipart/form-data' \
--form 'client_id="'$CLIENT_ID'"' \
--form 'pattern="front"' \
--form 'image=@"'/path_to/front_photo.jpg'"'

The following is an example request to send the right photo:

curl -X POST 'https://api2.bodygram.com/estimation/'$ESTIMATION_ID'/image' \
-H 'accept: application/json' \
-H 'Access-Token: '$ACCESS_TOKEN'' \
-H 'Content-Type: multipart/form-data' \
--form 'client_id="'$CLIENT_ID'"' \
--form 'pattern="right"' \
--form 'image=@"'/path_to/right_photo.jpg'"'

curl -X POST 'https://api2.stg.bodygram.cc/estimation/'$ESTIMATION_ID'/image' \
-H 'accept: application/json' \
-H 'Access-Token: '$ACCESS_TOKEN'' \
-H 'Content-Type: multipart/form-data' \
--form 'client_id="'$CLIENT_ID'"' \
--form 'pattern="right"' \
--form 'image=@"'/path_to/right_photo.jpg'"'

The following is an example response obtained from a successful request:

{
  "created_at": "2022-01-01T01:01:33.7",
  "estimation_id": "03KVW300KBJRZFBA29VDFD9AZW",
  "message": "Success",
  "send_input_queue": false,
}

Field send_input_queue should be set to true if and only if both photos have been succesfully received. This indicates that the measurement's estimation job has been properly scheduled on Bodygram's servers.

Get the Measurements

Finally, acquire the estimated measurements once they have been computed.

Request the measurements using the following parameters:

The following is an example request:

curl -X GET \
  'https://api2.bodygram.com/estimation/'$ESTIMATION_ID'?client_id='$CLIENT_ID \
  -H 'accept: application/json' \
  -H 'Access-Token: '$ACCESS_TOKEN \

curl -X GET \
  'https://api2.stg.bodygram.cc/estimation/'$ESTIMATION_ID'?client_id='$CLIENT_ID \
  -H 'accept: application/json' \
  -H 'Access-Token: '$ACCESS_TOKEN \

While we do our best to provide estimated measurement results as soon as possible, unexpected surges of traffic might increase the time required for Bodygram's servers to process your photos. In such instances, requests will receive responses indicating that the photos are still being processed (see status):

{
  "measurements": [{
    "created_at": "2022-01-01T01:02:33.7",
    "status": "in-progress",
    "estimation_id": "03KVW300KBJRZFBA29VDFD9AZW",
    "estimation": {}
  }],
  "message": "API Response Message",  
  "result": true,
}

Bodygram does not yet provide a callback system to inform you that the measurements have been computed. For now, we recommend polling the servers once every five seconds until you receive a response with status set to completed.

{
  "measurements": [{
    "created_at": "2022-01-01T01:03:33.7",
    "status": "completed",
    "estimation_id": "03KVW300KBJRZFBA29VDFD9AZW",
    "estimation": {
      "code": 101,
      "input": {
        "age": 33,
        "gender": "male",
        "height": 1778,
        "weight": 68500
      },
      "result": {
        "body_composition": {
          "body_fat_percentage": 20866,
          "skeletal_muscle_mass": 29097
        },
        "measurement": {
          "across_back_shoulder_width": 443,
          "back_neck_height": 1385,
          "back_neck_point_to_ground_contoured": 1408,
          "back_neck_point_to_waist": 414,
          "back_neck_point_to_wrist_length_r": 763,
          "belly_waist_girth": 796,
          "belly_waist_height": 940,
          "bust_girth": 932,
          "bust_height": 1160,
          "calf_girth_r": 372,
          "forearm_girth_r": 261,
          "hip_girth": 940,
          "hip_height": 785,
          "inside_leg_height": 716,
          "inside_leg_length_r": 657,
          "knee_girth_r": 370,
          "knee_height_r": 415,
          "mid_thigh_girth_r": 476,
          "neck_base_girth": 413,
          "neck_girth": 379,
          "outer_ankle_height_r": 60,
          "outer_arm_length_r": 544,
          "outseam_r": 960,
          "outside_leg_length_r": 1018,
          "shoulder_to_elbow_r": 301,
          "thigh_girth_r": 552,
          "top_hip_girth": 836,
          "top_hip_height": 880,
          "under_bust_girth": 865,
          "upper_arm_girth_r": 297,
          "waist_girth": 786,
          "waist_height": 970,
          "wrist_girth_r": 167
        },
        "status": "success",
        "version": "abc123",
        "work_id": "R5BFDG34VAFVF12O07"
      },
    }
  }],
  "message": "API Response Message",  
  "result": true,
}

Refer to the Measurements page for more information about the returned measurements.

Dealing with Errors

In some cases, the estimation job will complete with an error such as the following:

{
  "measurements": [{
    "created_at": "2022-01-01T01:02:33.7",
    "status": "in-progress",
    "estimation_id": "03KVW300KBJRZFBA29VDFD9AZW",
    "estimation": {
      "code": 306,
      "input": {
        "age": 33,
        "gender": "male",
        "height": 1778,
        "weight": 68500
      },
      "status": "fail",
      "version": "abc123",
      "work_id": "R5BFDG34VAFVF12O07"
    }
  }],
  "message": "API Response Message",  
  "result": true,
}

Errors are usually due to an issue with the uploaded photos (e.g. arm angle too small in the A pose). See the Error codes page for a list of all error codes and their meanings.

Do not hesitate to contact Bodygram developer support if you encounter any issues obtaining measurements.