How to translate MNE tables to API queries

This guide shows how to translate the process of getting data from MNE iTables searches to using the API using the Python Package.

Setup

[16]:
import beaapi

import pandas as pd
pd.set_option('display.max_rows', None)  # show all rows
pd.set_option('display.max_colwidth', None)  # show all text in cells
[3]:
# Get key from unversioned file
import os
from dotenv import load_dotenv
load_dotenv()
beakey = os.environ.get("beakey")

Walk-through

Step 1a: Choose DirectionofInvestment. The first page of the iTables query asks you to pick the “Investment Type” which roughly maps to DirectionOfInvestment

  • Choose “inward” for most “foreign direct investment in the United States” requests. However, for certain data (series ID = 8, 9) by U.S. state, choose “state”

  • Choose “outward” for most “United States direct investment abroad” requests. However, choose “parent” for “U.S. Direct Investment Abroad / Data on activities of multinational enterprises / Nonbank U.S. Parent Companies (data up to 2008)” or “U.S. Direct Investment Abroad / Data on activities of multinational enterprises /All U.S. Parent Companies (data for 2009 and forward)”

Step 1b & 2: Choose a SeriesID

  • The second question on first iTables page ask about the “Data Type” and this maps to a category of SeriesID (see below) that is then shown on the second iTables page (narrowed down given available DirectionOfInvestment).

DataType:

  • 1-21 & 46-61: Data on activites of multinational enterprises (AMNE)

  • 22-44: Balance of payments and direct investment position data

  • 62-69: Data on new foreign direct investment in the U.S.

[15]:
pd.read_csv("TA_MNE_series_list.csv").set_index('Series ID')
[15]:
Direction Note Short name
Series ID
0 NaN NaN All
1 inward/outward/parent NaN Assets
2 inward NaN Gross PPE
3 outward/parent NaN Capital Expenditures
4 inward/outward/parent NaN Sales
5 inward/outward/parent NaN Net Income
6 inward/outward/parent NaN Value Added
7 inward/outward/parent NaN Compensation
8 inward/outward/state/parent NaN Employment
9 state 1.0 Manufacturing Employment
10 inward/outward NaN Exports of Goods
11 defunct NaN Exports of Goods to the FPG
12 inward/outward NaN Imports of Goods
13 defunct NaN Imports of Goods from the FPG
14 inward/outward/parent NaN R&D
16 defunct NaN Balance Sheet
19 defunct NaN U.S. Trade in Goods
20 parent NaN Liabilities
21 parent NaN Owner's Equity
22 inward NaN Inward Position
23 inward NaN Inward Flows
24 inward NaN Inward Equity flows
25 inward/outward NaN Reinvestment of earnings
26 inward NaN Debt inflows
27 inward/outward NaN Direct investment income
28 inward 2.0 Inward Royalties Payments
29 inward 2.0 OPS, U.S. affiliates payments
30 outward NaN Outward position
31 outward NaN Outward flows
32 outward NaN Equity outflows
33 outward NaN Debt outflows
34 outward 2.0 Royalties, U.S. parents' receipts
35 outward 2.0 OPS, U.S. parents receipts
39 outward 2.0 Royalties U.S. parents' payments
40 outward 2.0 OPS, U.S. parents' payments
41 inward 2.0 Royalties, U.S. affiliates' receipts
42 inward 2.0 OPS, U.S. affiliates receipts
43 inward 2.0 Royalties, Net inward payments
44 inward 2.0 OPS, new inward payments
46 parent NaN U.S. Exports, parents to non affiliates
47 parent NaN U.S. Imports, from affiliates to parents
48 parent NaN U.S. Imports, from non-affiliates to parents
50 defunct NaN U.S. trade in goods of affiliates
51 defunct NaN Total assets, U.S. parent
52 defunct NaN Total assets, affiliates
53 inward NaN Inward PPE expenditures
54 outward NaN Net property, plant, and equipment
55 defunct NaN Sales of services
56 defunct NaN Sales of goods
57 parent NaN U.S. Exports, parents to foreign affiliates
58 outward NaN Goods supplied
60 outward NaN Services supplied
61 outward NaN Services supplied to foreigners
62 inward NaN Investment Expenditures
64 inward NaN Employment of new affiliates
66 inward NaN Sales of new affiliates
68 inward NaN Net income of new affiliates
69 inward NaN Balance sheet items of new affiliates

Notes:

  1. Requires classification="statebycountryofUBO", even though no country data are provided

  2. Prior to 2006 only

Step 3: Choose Classification

  • The classification depends on the direction and seriesID. The iTables are a guide as to which classifications are available

  • “CountrybyIndustry” will yield a large number of countries broken down by major industry. “IndustrybyCountry” will yield the opposite.

  • You can search for the iTables string in the table below

[17]:
beaapi.get_parameter_values(beakey, 'MNE', 'Classification').set_index('key')
[17]:
desc
key
Country Set to classification equal to 'country' to obtain data for all countries for which data are available for the given series, ownership, and year.
CountryByDestination CountryByDestination returns values for country broken out by destination for goods supplied and services supplied.
CountryByIndustry CountryByIndustry provides data for a large set of countries broken down by major industry.
CountrybyType Country by Type of Investment returns data on new foreign direct investment in the United States broken out by country of UBO and the type of investment (acquisition, establishment, or expansion).
CountryofUBO ? Presents data on foreign direct investment in the United States by the country of the Ultimate Beneficial Owner (UBO). The ultimate beneficial owner (UBO) is the entity, proceeding up the foreign ownership chain, which is not more than 50 percent owned by another entity. The UBO is the entity that ultimately owns or controls an affiliated and thus ultimately derives the benefits and assumes the risks from owning or controlling an affiliate.
CountryofUBObyDestination Presents data on services supplied by U.S. affiliates of foreign MNE?s, broken down by the country of Ultimate Beneficial Owner (UBO) and the destination (U.S. or foreign) of the service supplied
CountryofUBObyIndustry Presents data on foreign direct investment in the United States broken down by the country of the Ultimate Beneficial Owner (UBO) and the industry of the affiliate.
countryofUBObyType Country of UBO by Type of Investment returns data on new foreign direct investment in the United States broken out by the country of the Ultimate beneficial owner (UBO) and the type of investment (acquisition, establishment, or expansion).
Industry Set to classification equal to 'industry' to obtain data for all industries for which data are available for the given series, ownership, and year.
IndustryByCountry IndustryByCountry provides data for a large set of industries broken by major country.
IndustrybyCountryofUBO Presents foreign direct investment data broken down by industry of the U.S. affiliate and the country of Ultimate Beneficial Owner (UBO)
IndustryByDestination IndustryByDestination returns values for industry broken out by destination for goods supplied and services supplied.
IndustrybyType Industry by Type of Investment returns data on new foreign direct investment in the United States broken out by industry of U.S. business and the type of investment (acquisition, establishment, or expansion).
IndustryofSales Industry of Sales provides data on employment and sales for majority-owned U.S. affiliates of foreign MNEs. Each majority-owned U.S. affiliate above a minimum size threshold was required to distribute its sales and its employment among the four-digit industry in which it had sales. These data approximate an establishment-based distribution.
IndustryofUSParent = IndustryofUSParent provides data for foreign affiliates of U.S. parents, broken down by the industry of the U.S. parent, which may differ from the industry of the affiliate.
IndustryofUSParentAllIndustries IndustryofUSParentAllIndustries provides data for foreign affiliates of U.S. parents, broken down by the most detailed industry of the U.S. parent, which may differ from the industry of the affiliate.
IndustryofUSParentByCountry IndustryofUSParentByCountry provides data for foreign affiliates of U.S. parents, broken down by the industry of the U.S. parent, which may differ from the industry of the affiliate, and broken by major country.
StatebyCountryofUBO Presents selected activities of multinational enterprises data on U.S. affiliates, broken down U.S. state and country of UBO.
StatebyType State by Type of Investment returns data on new foreign direct investment in the United States broken out by destination state and the type of investment (acquisition, establishment, or expansion).
TypeofExpenditure Type of Expenditure returns values on investment expenditure for new foreign direct investment in the United States, broken out by type of expenditure.

Step 4: For AMNE estimates, Choose Ownershiplevel and Nonbankaffiliatesonly

  • Nonbankaffiliatesonly should be set to zero for any data from after about 2009.

  • More data are available for ownershiplevel = "0" (majority-owned affiliates only) than for ownershiplevel = "1" (all affiliates)

Step 5: Choose industry, country, year, etc…

  • This is pretty straightforward. Full lists are show below. Country = "all" and Industry = "all" yield all results. We show full available options for both below.

  • Years must be listed separately: Year = "2010, 2011, 2012, 2013" for example. Year = "all" returns all years

Countries:

[15]:
display(beaapi.get_parameter_values(beakey, "MNE", parametername="Country").style.hide_index())
key desc
all all
000 all Countries Total
600 Afghanistan
499 Africa
350 Albania
400 Algeria
300 Andorra
401 Angola
272 Anguilla
273 Antigua and Barbuda
200 Argentina
334 Armenia
274 Aruba
699 Asia and Pacific
601 Australia
898 Australia, New Zealand, and South Africa
301 Austria
335 Azerbaijan
250 Bahamas
501 Bahrain
631 Bangladesh
251 Barbados
336 Belarus
302 Belgium
254 Belize
409 Benin
252 Bermuda
602 Bhutan
201 Bolivia
358 Bosnia and Herzegovina
402 Botswana
202 Brazil
603 Brunei
351 Bulgaria
447 Burkina Faso
606 Burma
403 Burundi
450 Cabo Verde
607 Cambodia
404 Cameroon
100 Canada
450 Cape Verde
405 Central African Republic
297 Central America
406 Chad
203 Chile
650 China
204 Colombia
456 Comoros
407 Congo
407 Congo (Brazzaville)
408 Congo (Kinshasa)
205 Costa Rica
417 Cote D'Ivoire
359 Croatia
206 Cuba
275 Curacao
304 Cyprus
364 Czech Republic
352 Czechoslovakia
305 Denmark
390 Denmark, Greece, and Ireland
412 Djibouti
269 Dominica
207 Dominican Republic
660 East Timor
391 Eastern Europe
208 Ecuador
410 Egypt
209 El Salvador
438 Equatorial Guinea
457 Eritrea
331 Estonia
442 Eswatini
411 Ethiopia
399 Europe
392 European Communities (10)
393 European Communities (12)
398 European Union
657 Federated States of Micronesia
632 Fiji
306 Finland
307 France
256 French Guiana
255 French Islands, Caribbean
609 French Islands, Indian Ocean
610 French Islands, Pacific
413 Gabon
414 Gambia
337 Georgia
308 Germany
415 Ghana
309 Gibraltar
310 Greece
311 Greenland
265 Grenada
210 Guatemala
416 Guinea
430 Guinea-Bissau
257 Guyana
211 Haiti
212 Honduras
611 Hong Kong
354 Hungary
312 Iceland
612 India
613 Indonesia
999 International
998 International - Drilling Rigs
502 Iran
503 Iraq
509 Iraq-Saudi Arabia Neutral Zone
313 Ireland
504 Israel
314 Italy
417 Ivory Coast
258 Jamaica
614 Japan
505 Jordan
607 Kampuchea
338 Kazakhstan
418 Kenya
655 Kiribati
366 Kosovo
506 Kuwait
339 Kyrgyzstan
615 Laos
299 Latin America and Other Western Hemisphere
332 Latvia
507 Lebanon
419 Lesotho
420 Liberia
421 Libya
315 Liechtenstein
333 Lithuania
316 Luxembourg
616 Macau
422 Madagascar
423 Malawi
617 Malaysia
633 Maldives
424 Mali
317 Malta
658 Marshall Islands
425 Mauritania
453 Mauritius
213 Mexico
657 Micronesia
599 Middle East
340 Moldova
318 Monaco
651 Mongolia
361 Montenegro
426 Morocco
427 Mozambique
437 Namibia
635 Nauru
618 Nepal
319 Netherlands
259 Netherlands Antilles
277 Netherlands Islands, Caribbean
620 New Zealand
214 Nicaragua
428 Niger
429 Nigeria
652 North Korea
360 North Macedonia
320 Norway
508 Oman
899 OPEC
698 Other
899 Other Africa, Asia, and Pacific
394 Other EC
298 Other Western Hemisphere
622 Pakistan
659 Palau
215 Panama
619 Papua New Guinea
216 Paraguay
217 Peru
623 Philippines
355 Poland
321 Portugal
510 Qatar
356 Romania
341 Russia
432 Rwanda
637 Samoa
322 San Marino
451 Sao Tome and Principe
511 Saudi Arabia
433 Senegal
362 Serbia
454 Seychelles
434 Sierra Leone
625 Singapore
276 Sint Maarten
365 Slovakia
363 Slovenia
654 Solomon Islands
435 Somalia
436 South Africa
296 South America
296 South and Central America
626 South Korea
458 South Sudan
323 Spain
608 Sri Lanka
267 St. Kitts and Nevis
270 St. Lucia
263 St. Pierre and Miquelon
271 St. Vincent and the Grenadines
441 Sudan
260 Suriname
324 Sweden
325 Switzerland
512 Syria
628 Taiwan
342 Tajikistan
443 Tanzania
629 Thailand
660 Timor-Leste
444 Togo
638 Tonga
000 Total
699 Total Asia and Pac.
399 Total Europe
299 Total LA and OWH
261 Trinidad and Tobago
445 Tunisia
326 Turkey
343 Turkmenistan
656 Tuvalu
446 Uganda
344 Ukraine
357 Union of Soviet Socialist Republics
513 United Arab Emirates
327 United Kingdom
455 United Kingdom Islands, Atlantic (Africa)
268 United Kingdom Islands, Atlantic (OWH)
266 United Kingdom Islands, Caribbean
605 United Kingdom Islands, Indian Ocean
604 United Kingdom Islands, Pacific
199 United States
218 Uruguay
345 Uzbekistan
636 Vanuatu
330 Vatican City
219 Venezuela
653 Vietnam
440 Western Sahara
637 Western Samoa
514 Yemen
500 Yemen (Aden)
514 Yemen (Sanaa)
328 Yugoslavia
408 Zaire
448 Zambia
431 Zimbabwe

Industries:

[20]:
industries = beaapi.get_parameter_values(beakey, "MNE", parametername="Industry")
display(industries.head(5).style.hide_index())
key desc
all all
0000 All Industries Total
7210 Accommodation
7200 Accommodation and food services
5412 Accounting, tax preparation, bookkeeping, and payroll services

Examples:

U.S. Direct investment abroad, total position, by industry, 2015-2020:

  • U.S. Direct investment abroad requires directionofinvestment = outward

  • Position is seriesID = 30

  • Classification = industry

  • Year = 2015,…,2020

[6]:
beaapi.get_data(beakey, "MNE", DirectionOfInvestment="outward",
                Classification="Industry", SeriesID="30",
                Year="2015,2016,2017,2018,2019,2020", getfootnotes="yes").head(3)
[6]:
Year SeriesID SeriesName Row ColumnGParent ColumnParent Column RowCode ColumnCode ColumnParentCode ColumnGParentCode TableScale DataValueUnformatted TableColumnDisplayOrder TableRowDisplayOrder DataValue
0 2015 30 U.S. Direct Investment Position Abroad on a Hi... All Industries Total None None Position 0000 000 0 0 Millions of Dollars 5289071 1.00 1.00 5,289,071
1 2016 30 U.S. Direct Investment Position Abroad on a Hi... All Industries Total None None Position 0000 000 0 0 Millions of Dollars 5518644 1.00 1.00 5,518,644
2 2018 30 U.S. Direct Investment Position Abroad on a Hi... All Industries Total None None Position 0000 000 0 0 Millions of Dollars 5792290 1.00 1.00 5,792,290

Foreign direct investment in the United States, employment by majority-owned Canadian firms broken down by major industry, 2012 – 2019

  • Foreign direct investment in the United States requires directionofinvestment = inward

  • Employment series ID = 8

  • Classification is CountrybyIndustry

  • Majority-owned affiliates requires ownershiplevel = 0, Nonbankaffiliates = 0 for recent data

  • Canada country code = 100

  • Year = 2017, 2018, 2019

[5]:
beaapi.get_data(beakey, "MNE", DirectionOfInvestment="inward",
                Classification="CountrybyIndustry", SeriesID="8",
                Year="2012,2013,2014,2015,2016,2017,2018,2019", Country="100",
                getfootnotes="yes", Ownershiplevel="0", NonbankAffiliatesOnly="0").head(3)
[5]:
Year SeriesID SeriesName Row ColumnGParent ColumnParent Column RowCode ColumnCode ColumnParentCode ColumnGParentCode TableScale DataValueUnformatted TableColumnDisplayOrder TableRowDisplayOrder DataValue
0 2012 8 Employment Canada None None All Industries Total 100 0000 0 0 Thousands of Employees 560.8 1.00 15.50 560.8
1 2013 8 Employment Canada None None All Industries Total 100 0000 0 0 Thousands of Employees 580.9 1.00 15.50 580.9
2 2015 8 Employment Canada None None All Industries Total 100 0000 0 0 Thousands of Employees 641.4 1.00 15.50 641.4

Foreign direct investment in the United States, employment of majority-owned affiliates, by state and country, 2018

  • Foreign direct investment in the United States employment by state requires directionofinvestment = state

  • Employment series ID = 8

  • Classification is StatebyCountryofUBO

  • Majority-owned affiliates requires ownershiplevel = 0, Nonbankaffiliates = 0 for recent data

  • Year = 2018

[4]:
beaapi.get_data(beakey, "MNE", DirectionOfInvestment="state",
                OwnershipLevel="0", NonbankAffiliatesOnly="0",
                Classification="StatebyCountryofUBO", Year="2018",
                Country="all", seriesID="8", GetFootnotes="yes").head(3)
[4]:
Year SeriesID SeriesName Row ColumnGParent ColumnParent Column RowCode ColumnCode ColumnParentCode ColumnGParentCode TableScale DataValueUnformatted TableColumnDisplayOrder TableRowDisplayOrder DataValue
0 2018 8 Employment Total States and Areas None None --- All Countries Total 00 000 0 0 Thousands of Employees 7862.2 1.00 1.00 7,862.2
1 2018 8 Employment Total States and Areas None None Canada 00 100 0 0 Thousands of Employees 837.4 2.00 1.00 837.4
2 2018 8 Employment Total States and Areas Europe Total Total 00 000 000 399 Thousands of Employees 4923.2 3.00 1.00 4,923.2

New foreign direct investment in the United States, Investment expenditures by type, by country, all years available

  • New foreign direct investment in the United States requires directofinvestment = inward

  • Series ID = 62

  • Classification is CountryofUBObyType

  • Year = all

[3]:
beaapi.get_data(beakey, "MNE", DirectionOfInvestment="inward",
                Classification="CountryofUBObyType", Year="all",
                seriesID="62", GetFootnotes="yes").head(3)
[3]:
Year SeriesID SeriesName Row ColumnGParent ColumnParent Column RowCode ColumnCode ColumnParentCode ColumnGParentCode TableScale DataValueUnformatted TableColumnDisplayOrder TableRowDisplayOrder DataValue
0 2020 62 Investment Expenditures All Countries Total First-year expenditures Total Total 000 000 000 111 Millions of dollars 120674 1.00 1.00 120,674
1 2019 62 Investment Expenditures All Countries Total First-year expenditures Total Total 000 000 000 111 Millions of dollars 221215 1.00 1.00 221,215
2 2014 62 Investment Expenditures All Countries Total First-year expenditures Total Total 000 000 000 111 Millions of dollars 260487 1.00 1.00 260,487

U.S. parent companies, assets, by industry, 2018

  • U.S. parent companies requires directionofinvestment = parent

  • Series ID = 1

  • Classification = industry

  • U.S. parent data requires ownershiplevel = 1, Nonbankaffiliates = 0 for recent data

  • Year = 2018

[9]:
beaapi.get_data(beakey, "MNE", DirectionOfInvestment="parent",
                Classification="Industry", SeriesID="1", Year="2018",
                getfootnotes="yes", Ownershiplevel="1", NonbankAffiliatesOnly="0").head(3)
[9]:
Year SeriesID SeriesName Row ColumnGParent ColumnParent Column RowCode ColumnCode ColumnParentCode ColumnGParentCode TableScale DataValueUnformatted TableColumnDisplayOrder TableRowDisplayOrder DataValue
0 2018 1 Total Assets All Industries Total None None Total Assets 0000 180 0 0 Millions of Dollars 43783215 1.00 1.00 43,783,215
1 2018 1 Total Assets Mining None None Total Assets 2198 180 0 0 Millions of Dollars 562877 1.00 16.50 562,877
2 2018 1 Total Assets Oil and Gas Extraction None None Total Assets 2111 180 0 0 Millions of Dollars 277707 1.00 17.50 277,707
[ ]: