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 availableDirectionOfInvestment
).
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:
Requires
classification="statebycountryofUBO"
, even though no country data are providedPrior 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 forownershiplevel = "1"
(all affiliates)
Step 5: Choose industry, country, year, etc…
This is pretty straightforward. Full lists are show below.
Country = "all"
andIndustry = "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 |
[ ]: