PriceUpload API

The PriceUpload API allows authorized users to upload price data files to the FPMA system. This operation is restricted to logged-in users with the necessary permissions. Users must first authenticate using the Login API to obtain an access token.

Authentication

Login API

URL: [POST] https://fpma.fao.org/giews/v4/global/api/token/

Body Parameters:

{
  "username": "",
  "password": ""
}

Example Response:

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJh.eyJ0b2t…………",
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOi…………."
}

The access field contains the Bearer token, which is required for authorization when using the PriceUpload API.

Upload API

Endpoint:

[POST] https://fpma.fao.org/giews/v4/global/price_module/api/v1/PriceUpload/

Headers:

• Authorization: Bearer {{access}}Replace {{access}} with the Bearer token obtained from the Login API.

Request Body:

{
  "files": "// the file to upload",
  "description": "description of the file"
}

Example Response:

• Success:

  {
    "status": "success",
    "message": "Thank you for uploading files for prices. We'll email you when the process is done."
  }

• Failure:

  {
    "status": "failed",
    "message": "....."
  }

File Requirements

The API accepts files in comma-separated value (CSV) format with UTF-8 encoding. Each field in the CSV file must be enclosed in double quotes ("") except for the Header. The CSV file must include the following header row as the first line:

Header Row

ID, ISO3_COUNTRY_CODE, PRICE_TYPE, PERIODICITY, MARKET, COMMODITY, DATE, PRICE_VALUE, CURRENCY, MEASURE_UNIT, SOURCE

Field Descriptions and Requirements:

• id: Leave blank ("").
• iso3_country_code: Must be a valid ISO 3166-1 alpha-3 country code.
• price_type: Must match one of the exact string values available in the database's Price Types table.
• periodicity: Must be one of "DAILY", "WEEKLY", or "MONTHLY".
• market: Must match one of the exact string values available in the database's Markets table.
• commodity: Must match one of the exact string values available in the database's Commodities table.
• date: Must follow the format yyyy-mm-dd. For WEEKLY data, the date should correspond to the last day of the week.
• price_value: Use a period (.) as the decimal separator.
• currency: Must be a valid ISO 4217 currency code.
• measure_unit: Must match one of the exact string values available in the database's Measure Units table.
• source: Must match one of the exact string values available in the database's Sources table.

Important Considerations

Data Consistency

Ensure all fields are properly formatted and match the exact string values as required. Improper formatting or mismatched values will result in a failed upload.

File Size Limit

It is recommended to keep uploads manageable in size to prevent timeouts and reduce computational load. Large datasets should be split into smaller files and uploaded separately. It is advisable to upload files with a maximum of 5,000 records at a time.

Example Usage of PriceUpload API

To demonstrate how to use the PriceUpload API, here are examples in JavaScript (using Fetch API) and Python (using requests library).

Code Examples

http://localhost:3000

Javascript

const fetch = require('node-fetch'); // If using Node.js, you need to install node-fetch

async function uploadPriceData() {
    // Replace with your actual username and password
    const loginData = {
        username: 'your_username',
        password: 'your_password'
    };

    // Step 1: Obtain Bearer Token
    const loginResponse = await fetch('https://fpma.fao.org/giews/v4/global/api/token/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(loginData)
    });

    const loginResult = await loginResponse.json();
    const accessToken = loginResult.access;

    // Step 2: Upload the price data file
    const uploadData = new FormData();
    uploadData.append('files', new File(['your_file_content'], 'prices.csv', { type: 'text/csv' }));
    uploadData.append('description', 'Description of the uploaded file');

    const uploadResponse = await fetch('https://fpma.fao.org/giews/v4/global/price_module/api/v1/PriceUpload/', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${accessToken}`
        },
        body: uploadData
    });

    const uploadResult = await uploadResponse.json();
    console.log(uploadResult);

}

uploadPriceData().catch(console.error);

Python

import requests

# Step 1: Obtain Bearer Token
login_url = 'https://fpma.fao.org/giews/v4/global/api/token/'
login_data = {
    'username': 'your_username',
    'password': 'your_password'
}

login_response = requests.post(login_url, json=login_data)
login_result = login_response.json()
access_token = login_result['access']

# Step 2: Upload the price data file
upload_url = 'https://fpma.fao.org/giews/v4/global/price_module/api/v1/PriceUpload/'
headers = {
    'Authorization': f'Bearer {access_token}'
}

files = {
    'files': ('prices.csv', open('path_to_your_file.csv', 'rb'), 'text/csv')
}
data = {
    'description': 'Description of the uploaded file'
}

upload_response = requests.post(upload_url, headers=headers, files=files, data=data)
upload_result = upload_response.json()
print(upload_result)

Key Points in the Examples:

1. Authentication:
   • Both examples start by sending a POST request to the Login API to obtain an access token.
   • The token is then used in the Authorization header of the subsequent POST request to the PriceUpload API.
2. File Upload:
   • In the JavaScript example, FormData is used to send the file and description.
   • In the Python example, the file is opened in binary mode and included in the files parameter.
3. Handling the Response:
   • The API response, which includes a success or failure message, is printed to the console in both examples.

Ensure that the file paths and user credentials are correctly set in the code. These examples demonstrate how to interact with the FPMA Tool APIs programmatically, making it easier to automate data uploads.